Coulomb should make **both** styles of knowledge work feel natural:
| Mode | Flow |
|------|------|
| **Top-down** | Title → short description (abstractor) → outline → elaborate body → optional visual |
| **Bottom-up** | Plunge into body text → title / abstractor / structure / visual emerge after or while writing |
Neither mode may force the other. Empty or content-only entities must still **display** as first-class cards (title, description, illustration) without blocking the writer.
## Principles
1.**Body is never blocked** on metadata. A page with only prose is valid.
2.**Display needs projections** — card/list UI needs title, abstractor, visual when showing an entity.
3.**Projections may start virtual** — generated on first need (lazy), then **persisted as normal field values**.
4.**After persistence, fields behave like user-authored data** — editable, exportable in frontmatter, same SoR as hand-written values.
5.**Regenerate** is an explicit action, not ambient rewriting.
6.**Lock** freezes a field against automatic (and optionally against bulk) regeneration.
7.**Structure stays page-first** — outline is headings/sections in the markdown body (or a derived outline view), not a separate chunk ontology. See `transclusion-and-chunks.md`.
---
## Field set (stage-1 aligned)
| Field | Role | Display use |
|-------|------|-------------|
| **title** | Name of the entity | Card headline, browser title, lists |
| **body** | Main markdown content | Full page view |
| **outline** | Derived (usually) from body headings | Top-down scaffold; navigation |
`outline` is typically **not** a separate SoR blob: it is **read from**`#` / `##` structure, or optionally written back as a stub section when the user accepts a generated outline in top-down mode.
---
## Dual mode UX
### Top-down path
```text
New page
→ focus title (optional visual placeholder)
→ abstractor
→ "Generate outline" → body becomes heading skeleton
→ user elaborates under headings
→ visual optional (upload or generate)
```
- Empty body with title/abstractor is fine.
- Outline generation **writes body** (or a dedicated outline region) only when the user asks — not on every keystroke.
### Bottom-up path
```text
New page / open blank body
→ write freely
→ on first card/list display (or idle debounce): lazy-fill missing title/abstractor/visual
→ user may edit, regenerate, or lock any field
→ optional "Propose outline" restructures headings without deleting prose carelessly
```
- Creating a page must not require a title dialog.
- Autosave body continuously; projections fill **lazily on display need** or on explicit "Suggest metadata".
### Mode switching
There is **no mode toggle the user must set**. The product infers intent:
- If title/abstractor present and body empty → treat as top-down.
- If body present and title empty → bottom-up; lazy projections allowed.
- Both filled → normal edit; regenerate only on demand.
| **user** | Value present; last material edit was human (or import); unlocked |
| **locked** | Value fixed; no auto/lazy regenerate; explicit unlock required |
**Rule:** Once generated and saved, the value is **kept** as if the user had typed it — cards and export see real frontmatter, not a live prompt every time.
**Lazy trigger examples:**
- First render of a card in a list/deck when `title` or `abstractor` or `visual` is absent
- Opening page header chrome when fields missing
- Explicit “Fill missing metadata”
**Not triggers (by default):**
- Every keystroke in the body
- Background jobs that rewrite locked or recently user-edited fields
| `feat.projection-lock` | Per-field lock against auto/regenerate |
Stage-1: ship dual authoring + lazy title/abstractor at minimum; visual generation can start as placeholder art; LLM optional.
---
## Anti-patterns
| Avoid | Why |
|-------|-----|
| Requiring title before first save | Blocks bottom-up |
| Regenerating on every body keystroke | Noisy, fights the writer |
| Virtual-only fields that never save | Breaks export and “user’s data” |
| One global “AI mode” toggle for the whole page | Prefer per-field lock/regenerate |
| Separate chunk entities only to hold outline | Outline is page structure |
---
## Open product choices
1.**Default generator set** — deterministic only vs LLM when configured.
2.**Stale derived fields** — badge-only vs optional auto-refresh.
3.**Visual generation** — placeholder vs asset pipeline vs external image model.
4.**Outline write-back** — always mutate body vs ephemeral outline panel until “Apply”.
5.**Space-level projections** — same contract for space cards (title/abstractor/visual).
---
## One-liner
**Top-down and bottom-up are both first-class; display fields can be born lazy, then live as ordinary locked-or-editable metadata so tooling never blocks the writing.**
