@synap-core/cli 1.10.0 → 1.12.2

package/skills/synap/workspace-design.md

@@ -1,6 +1,8 @@
 ## Workspace design — is this concern a WORKSPACE, or something smaller?
 
-Before you create a workspace, run the decision rule. A workspace (an operational **domain**) is the heaviest structure in the pod — it owns kinds, confers roles, carries its own team and automations. Most new concerns are NOT domains; they are a **hat**, an **initiative**, or a **stage**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create.
+Before you create a workspace, run the decision rule. A workspace (an operational **domain**) is the heaviest structure in the pod — it owns kinds, confers roles, carries its own team and automations. Most new concerns are NOT domains; they are a **hat**, an **initiative**, a **lasting goal** (track), or a **status**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create. What each word means: `concepts` (the one glossary).
+
+**One space per domain:** A space is a domain, installed once (Content, Brand, CRM…). A project is a filter across spaces. To make something “for project X”: file it into X inside the domain's space (`file_into_project`), and link X to the space (`project_use_workspace`). Never create a space named after a project, a brand or a client.
 
 ## The decision rule — a concern earns a workspace ONLY if ALL FOUR hold
 
@@ -11,20 +13,22 @@ Before you create a workspace, run the decision rule. A workspace (an operationa
 
 **All four, or it is not a workspace.** Then fork it to the right lighter structure:
 
-| If the concern is…                                          | It is a…       | Substrate                              | Example                                     |
-| ----------------------------------------------------------- | -------------- | -------------------------------------- | ------------------------------------------- |
-| a **role/hat** an existing entity wears in a domain         | **Facet**      | `attach_facet` (`profileKind: "role"`) | `client`, `sponsor`, `prospect`, `investor` |
-| a **cross-cutting, time-bound initiative** spanning domains | **Project**    | `create_project` (a lens)              | a campaign, an engagement, a launch         |
-| a **stage/filter WITHIN a domain**                          | **State/View** | a `status` property def + a view       | pipeline stage, "active"/"archived"         |
+| If the concern is…                                          | It is a…    | Substrate                              | Example                                     |
+| ----------------------------------------------------------- | ----------- | -------------------------------------- | ------------------------------------------- |
+| a **role/hat** an existing entity wears in a domain         | **Facet**   | `attach_facet` (`profileKind: "role"`) | `client`, `sponsor`, `prospect`, `investor` |
+| a **cross-cutting, time-bound initiative** spanning domains | **Project** | `create_project` (a lens)              | a campaign, an engagement, a launch         |
+| a **lasting goal** a project pursues (worked in sessions)   | **Track**   | `start_track` (no method needed)       | grow the newsletter, win ten clients        |
+| a **stage/filter WITHIN a domain**                          | **Status**  | an option of the kind's lifecycle      | pipeline stage, "active"/"archived"         |
 
 ## The decision procedure (follow in order)
 
 1. **Name the source-of-truth noun.** What kind would this workspace _own_ that no existing workspace owns? Run `list_profiles` — if the noun already lives in another domain, you have a facet or a project, not a domain. STOP.
 2. **Test all four conditions.** Owns kinds AND own team AND native automations AND stable. Any one fails → fork below.
-3. **If it's a hat** (a status/role on an entity that already exists elsewhere) → resolve the entity, `attach_facet`. Never a workspace, never a second entity.
+3. **If it's a hat** (a status/role on an entity that already exists elsewhere) → resolve the entity, `attach_facet`. Never a workspace, never a second entity. One role per name, pod-wide: a role several workspaces use is ONE role, each workspace adding properties by overlay — never a per-workspace twin (`concepts`).
 4. **If it's time-bound work across domains** → `create_project` and set it as the lens; the work files into it from whatever workspace holds the data. **A project is a COMMITMENT WITH GRAVITY** — a real initiative that ties work together (a campaign, an engagement, a client, a launch). Tasks, plans, repos, themes, and topics are **entities**, never projects. Before you create one: (a) **search existing projects first** (`synap orient` / `GET /api/hub/projects`) and prefer **linking into an existing project** via `belongs_to_project` — near-duplicate names are rejected with the existing candidates; (b) an agent-created project must cite **≥5 existing entities** that would belong to it as `evidenceEntityIds` — the backend rejects a project with no gravity and tells you to store it as an entity or reuse an existing project instead; (c) **never create a project for the pod owner's own company** — the company _is_ the pod, not a project inside it.
-5. **If it's a stage inside a domain** → add a `status` property def (`create_property_def`) and a view; don't split the stage into its own space.
-6. **Only if all four held** → **template first** (escalation ladder L3):
+5. **If it's a lasting goal a project pursues** ("keep the content side of the launch going") → a **track**: `list_tracks`, else `start_track` (`name`, `direction`); work in it with `start_session` + `trackId`. Never a workspace, never a twin project.
+6. **If it's a stage inside a domain** → it is an option of the kind's or role's declared lifecycle, never a role and never a space. Its pipeline is computed from the lifecycle: open it, don't build one. A kind with no lifecycle yet gets a `status` property def (`create_property_def`).
+7. **Only if all four held** → **template first** (escalation ladder L3):
    `market.search({query, kind: "template"})` and propose install of a matching
    template before freehand `create_workspace`. Freehand create is last resort
    and always proposed — a deliberate move, offer it to the user (see
@@ -32,7 +36,7 @@ Before you create a workspace, run the decision rule. A workspace (an operationa
 
 ## The CRM corollary — the load-bearing example
 
-Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + a triggered project**, NEVER as workspaces and NEVER by bolting delivery onto the identity domain.
+Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + an engagement project** (its delivery runs as a track), NEVER as workspaces and NEVER by bolting delivery onto the identity domain.
 
 - CRM = **who** (owns `person`/`company`, confers the `lead`/`client` facets).
 - Operations = **what we do for them** (owns `engagement`/`contract`/`deliverable`).

package/skills/synap/writes.md

@@ -1,6 +1,30 @@
 ## Core writes
 
-### Create an entity (schema-first, complete intent)
+> **Scope of this page.** It covers writes that produce ENTITY-shaped data.
+> There are ~30 other write tools (sessions, capabilities, automations, cells,
+> playbooks, views, channels…) that this page does not orient across — reach for
+> `synap_list_capabilities` / the escalation ladder for those. If you are about
+> to pick a tool and the choice feels ambiguous, that ambiguity is real: the
+> tools below differ in ATOMICITY and COLLISION policy, not just in shape.
+
+**Two entity-write doors, one gradient.** `create_entity` is for exactly ONE
+fully-structured, typed entity you already have. For anything unstructured,
+several entities, or a graph — or **when in doubt** — use the capture door
+(`synap_capture`, see `capture.md`): precision comes from sending more structure
+in the SAME call, never from picking a different tool or a second commit step.
+
+The difference that is NOT visible in either tool's description: `create_entity`
+writes one entity with per-entity governance and REJECTS a name collision unless
+`forceCreate`; capture-with-`entities[]` files ONE atomic proposal for the whole
+graph and DEDUP-MERGES instead of rejecting. Pick by whether you want a partial
+write to be possible, not by how structured your data feels.
+
+**Every title is linted.** Both doors return `titleLint` in the receipt when a
+title breaks the rubric (too long, cut off, status words, ids, a placeholder…);
+the title is stored as sent, so rewrite it. Over 200 characters the write is
+refused. Title rules and what counts as knowledge: `writing-titles.md`.
+
+### Create an entity (one exact typed entity)
 
 Before this call, use `/discover?userId=…&profileSlugs=<kind>` to read the
 real fields, required/default values, constraints and reference targets. Omit
@@ -22,15 +46,28 @@ POST /api/hub/entities
 ```
 
 The response has legacy `status`/`id` fields plus `writeReceipt`:
-`pending` means a proposal exists and no entity is live; `applied` means the
-reported direct write completed; `partial` means a follow-up (for example a
-facet) failed after the entity applied. Never claim completion from `pending`,
-and only enrich again when the receipt identifies a real missing fact.
+`pending`/`proposed` means a proposal exists and no entity is live yet;
+`applied` means the reported direct write completed; `partial` means a follow-up
+(for example a facet) failed after the entity applied. **A `proposed`/`pending`
+receipt is a governed success, not an error** — you MUST surface its
+`reviewUrl` as a clickable markdown link in the same reply (see
+`inline-patterns.md`), never claim completion, and only enrich again when the
+receipt identifies a real missing fact.
 
 For several entities, creation-time roles/facets, or relations that need one
-review, submit one `POST /api/hub/capture/graph` plan instead of sequencing
-independent creates. It returns a pending receipt and materializes on human
-approval.
+review, send the whole graph through the capture door (`synap_capture` with
+`entities[]` + `relations[]`) instead of sequencing independent creates. It is
+ONE governed call: policy auto-applies when every op is safe, otherwise the
+whole graph is proposed (atomic). There is no separate commit step.
+
+**Name-refs, not UUIDs.** Reference an existing project by name — the server
+resolves it against the caller's own projects (exact match files there; no match
+proposes, never mis-files). Never ask the user for a UUID.
+
+**Dedup is advisory across kinds.** Strong signals (`email`/`phone`/`website` —
+not a bare `url`) dedup within a kind; a same-title hit in a _different_ kind
+comes back as an advisory candidate, never an auto-merge. "No exact match" is not
+"safe to create" when advisory candidates are returned — review them first.
 
 ### Update an entity
 
@@ -41,6 +78,70 @@ PATCH /api/hub/entities/{entityId}
 
 **Properties are deep-merged — send only the keys you want to change.** An update with `{ "status": "done" }` leaves all other properties untouched. You never need to re-send the full properties object.
 
+**Many changes → ONE call: `synap_update_entities`** (up to 500 items
+`{id, patch, expected?}`; Hub: `POST /api/hub/entities/batch-update`). Never
+script a loop of single updates, and never apply a change set over Hub REST with
+a user key. Governance is per item: some apply now, the rest ride ONE review for
+the person; the answer lists `applied` / `proposed` / `denied` / `skipped` — a
+partial result is normal. Send `validate: true` first to see each verdict without
+writing, and an `idempotencyKey` so a retry never acts twice.
+
+**A write blocked on a space join is KEPT.** When you write into a space your
+agent has not joined (`synap_orient` marks it `joined: false`), the answer is
+`proposed` with `proposalType: "join"`, `deferred: true` and a `ref`: the write
+rides the join request and is replayed for you once it is approved. Do not
+resend it, and do not retry it into another space.
+
+**Moving, not recreating.** A session into another space:
+`synap_update_session` with `moveToWorkspaceId` (never `workspaceId` — that is
+the connection's lens). A kind another space needs: `synap_change_kind_scope`
+(`scope: "shared"` + `allowedWorkspaceIds`), never a twin kind. Records:
+`synap_move_entities`. All three are reviewed.
+
+### Authored text is content, not a `file`
+
+Something **you** author — a pitch deck, a strategic plan, a note body — is
+**never** a `file`- or `document`-kind entity. Create it as the right CONTENT
+kind (`note`, `knowledge`, or a fitting domain kind) with `content` set to the
+Markdown body; Synap **auto-materializes** that `content` into a real
+versioned document behind the scenes (`entities WHERE documentId = ?`) — no
+upload step needed. `file` is reserved for real uploaded bytes you actually
+have (`synap_store_file`; over 10MB `synap_request_upload`) — authored text
+never becomes a `file`. Reach for `synap_create_document` /
+`POST /api/hub/documents` directly only for a standalone rich document that
+isn't itself a title-worthy entity (see below) — never as a substitute for an
+entity's `content`.
+
+### "I want to add a real FILE" — the decision tree
+
+You CAN store content you **hold** — you send it inline. Pick by what you have:
+
+| You have…                                                                                   | Do this                                                                                         | Result                                                               |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Content in hand** — a report/CSV/image/PDF/etc. you generated or received (text or bytes) | **`synap_store_file`** (`content` for text, `contentBase64` for binary) + `mimeType`/`filename` | a `file` entity, content stored **as-is, never read** (≤10MB inline) |
+| Text you're **authoring as a note/idea** (not "a file") — a plan, a thought                 | `synap_create_entity` with `content` (a content kind)                                           | body auto-becomes a document — NOT a `file`                          |
+| Only a **URL/link** (no bytes) — a Google Doc, a PDF url, an article                        | `synap_create_document` with **`url`**, or attach via `entityId`                                | an external **reference** document (no bytes)                        |
+| A **large file** (over 10MB, up to 500MB video)                                             | `synap_request_upload` → PUT the bytes to `uploadUrl` → `synap_store_file({ uploadToken })`     | a `file` entity backed by stored bytes                               |
+| Only a file's **name**, nothing else                                                        | you **cannot** invent it — ask the human/client to provide the content or a link                | —                                                                    |
+
+**A typed thing with a file → the KIND first, the bytes on it.** When a kind
+exists for the thing (a logo is a `brand-asset`, not a `file`; check the space
+brief or `synap_list_profiles`): (1) resolve-or-create that entity
+(`synap_ask`, then `synap_create_entity`); (2) `synap_store_file` with
+`attachToEntityId` = its id (`content` for SVG/text, `contentBase64` for
+binary, ≤10MB inline; larger: `synap_request_upload`, then `uploadToken`); (3) link it /
+`synap_file_into_project` if asked. A `proposed` create has no live id yet —
+attach after approval. A bare `file` is only for bytes with no kind.
+
+**Store ≠ analyze.** `synap_store_file` / `synap_create_document` store content
+**deterministically — the file is NEVER read by an LLM.** Only fetch a document
+and reason over it when the user explicitly says "read/analyze this file."
+
+**Do NOT over-structure a file request.** "Store this file" / "how do I add this
+file" is ONE intent → at most one stored file (plus, only if asked, a linking
+relation). Never inflate it into a task + note + placeholder-file scaffold, and
+never dump the request text into a note and call it done.
+
 ### Create a document (attach to an entity)
 
 ```json
@@ -53,11 +154,19 @@ POST /api/hub/documents
   "type": "markdown",              // "markdown" | "html" | "text" | "code"
   "entityId": "ent_event_..."      // attach to an entity for context
 }
+// → { "id": "doc_abc", "documentId": "doc_abc", "status": "created", "ackState": "applied",
+//     "attached": { "entityId": "ent_event_...", "documentId": "doc_abc", "status": "updated" } }
 ```
 
+`attached` reports the attach outcome: it is a governed entity update, so it can
+be `proposed`, and it is `skipped` (with a `reason`) while the document itself is
+awaiting review. Other optional fields: `url` (an https link — creates a reference
+document with no stored bytes), `idempotencyKey` (a retry with the same key returns
+the prior document), `expectedLabel` (the session-output slot it fulfils).
+
 `type: "html"` stores self-contained HTML. The browser renders it via the `html-doc` cell in a sandboxed iframe. Use for AI-generated reports, rich visualisations, custom charts, or anything beyond markdown.
 
-**Full HTML cell workflow** (AI → visible custom UI in any bento):
+**HTML document workflow:**
 
 ```json
 // 1. Create the HTML document
@@ -66,53 +175,72 @@ POST /api/hub/documents
   "title": "Q2 Revenue Report", "type": "html",
   "content": "<!DOCTYPE html><html>…</html>",
   "entityId": "ent_project_..." }
-// → { "document": { "id": "doc_abc" }, ... }
-
-// 2. Place the html-doc cell in any bento view
-POST /api/hub/views/{bentoViewId}/arrange
-{ "userId": "{userId}", "workspaceId": "{workspaceId}",
-  "widgets": [
-    { "id": "b1", "kind": "html-doc", "config": { "documentId": "doc_abc" },
-      "layout": { "x": 0, "y": 0, "w": 8, "h": 6 } }
-  ] }
+// → { "id": "doc_abc", "documentId": "doc_abc", "status": "created", ... }
 
-// 3. Update the HTML (cell auto-refreshes)
+// 2. Replace the HTML (read it first: GET → `revision`)
 PATCH /api/hub/documents/doc_abc
-{ "userId": "{userId}", "content": "<!DOCTYPE html>…updated…</html>" }
+{ "userId": "{userId}", "content": "<!DOCTYPE html>…updated…</html>", "baseRevision": 3 }
+// → a pending proposal; readers see the new HTML only once it is approved
 ```
 
+`html-doc` is **not** an agent-placeable bento widget: `arrange` rejects it. The
+document renders where it is opened (the Files app, or the entity it is attached
+to). For HTML you want to embed elsewhere, create an HTML cell instance
+(`POST /api/hub/cell-instances/html`) and embed it by `instanceId`.
+
 The iframe uses `sandbox="allow-scripts"` — scripts run but have no same-origin access to the parent app. The HTML is fully isolated.
 
-### Update a document (title and/or content)
+### Update a document's content (a patch, reviewed)
+
+Change the part you mean, not the whole body. Read it first —
+`GET /api/hub/documents/{id}?userId={userId}` → `content`, `revision`,
+`sections` (id + owner) — then:
 
 ```json
-PATCH /api/hub/documents/{documentId}
+POST /api/hub/documents/{documentId}/patch
 {
   "userId": "{userId}",
-  "title": "Updated title",          // optional
-  "content": "# Full replacement\n…" // full string — not a diff
+  "baseRevision": 3,
+  "ops": [
+    { "op": "replace_text", "old": "ships on Friday", "new": "ships on Monday" },
+    { "op": "upsert_section", "id": "risks", "title": "Risks", "body": "None yet." }
+  ]
 }
 ```
 
-Content is a **full replacement**, not a patch. Fetch the current content first if you want to append: `GET /api/hub/documents/{id}?userId={userId}` → `.content`, append, then PATCH.
+Ops: `upsert_section {id, title, body}` (one section by id), `replace_text {old,
+new}` (`old` must match **exactly once**, else 400 with the count), `append
+{body}`, `replace_all {content}`. An agent's edit is filed as a proposal (a
+governance rule may apply it directly); a person's section (`owner="human"`) is
+never changed and an embed is never dropped unless you pass
+`"allowRemovingEmbeds": true` (403 otherwise). A moved document answers 409 and
+nothing is written: read again. An applied or approved edit reaches open editors
+(`document:content-replaced`), so they reload instead of overwriting it. `PATCH /api/hub/documents/{id}` with `content` is the same door with
+one `replace_all` — it cannot rename (a `title` is refused with 400; to rename an
+entity's document, update the entity's title). MCP: `synap_update_document`;
+full syntax in `document-embeds.md`.
 
 The reverse lookup is `entities WHERE documentId = ?`. Always attach the document to a meaningful entity (the meeting event, the project, the person) — a floating document is another orphan.
 
-### Store a fact (memory) — use sparingly
+### Remember a fact about the user — use sparingly
 
-```json
-POST /api/hub/memory
-{ "userId": "{userId}", "fact": "User prefers async communication over meetings" }
-```
+A fact _about the user_ goes through `remember_fact` (CLI: `synap capture --type
+observation`). It writes a governed `user_observation` — not an ungoverned
+throwaway row: a fact the user explicitly stated auto-approves; a fact you
+inferred returns `proposed` (normal — surface the review link). Because it's a
+real entity it's addressable, linkable and revertible.
 
-Always auto-approved. **Memory is for loose, unstructured, hard-to-title facts only.** The seductive thing about memory is it has zero friction — no dedup, no linking, no proposals. That makes it easy to misuse.
+**Use it only for loose, unstructured, hard-to-title facts about the user** — a
+stated preference, a throwaway detail. Everything with a title-worthy noun or
+something to link to is an ENTITY through the capture door, not an observation.
 
-**The test:** if the user later asked "show me all X," can memory answer? Memory can only keyword-match — it has no structure. So:
+**The test:** if the user later asked "show me all X," could a loose observation
+answer? It can only keyword-match — it has no structure. So:
 
 | Input                                                   | Use                                                             |
 | ------------------------------------------------------- | --------------------------------------------------------------- |
-| "User prefers async communication"                      | memory — it's a preference                                      |
-| "Garage code is 4321"                                   | memory — throwaway fact                                         |
+| "User prefers async communication"                      | observation — it's a preference                                 |
+| "Garage code is 4321"                                   | observation — throwaway fact                                    |
 | "Should we use LangGraph or CrewAI for Eve?"            | **entity `question`** — substantive inquiry, start of flow      |
 | "Here's what I found comparing LangGraph and CrewAI…"   | **entity `research`** — investigation with sources + conclusion |
 | "We decided to use LangGraph over OpenClaude's native…" | **entity `decision`** — has title, rationale, project           |
@@ -122,7 +250,7 @@ Always auto-approved. **Memory is for loose, unstructured, hard-to-title facts o
 | "Action item from meeting: ship MVP by Friday"          | **entity `task`** linked to the `event` (meeting)               |
 | "Agreed with Sarah: we'll split backend & frontend"     | **entity `decision`** linked to Sarah + the project             |
 
-**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity, not memory. Memory is the fallback, not the default.
+**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity through the capture door, not an observation. A user observation is the fallback, not the default.
 
 **For decisions specifically** — use the `decision` system profile:
 
@@ -145,6 +273,8 @@ POST /api/hub/entities
 
 This creates a first-class decision entity linked to Project Eve. It shows up in traversals, can be superseded later (`supersededBy: newDecisionId`), and survives governance. Memory can't do any of that.
 
+**A decision the PERSON must make** — create it with `decisionStatus: "proposed"` and the pod asks them for you: pass `decisionOptions` (≤8 of `{label, value?, description?}`) and `recommendedOption` (an option's `value`, else its `label`); set `sourceSessionId` to keep the question in your session. Their answer UPDATES that decision — never create a second one. Every answered `confirm`/`choose` ask already files its decision (`slot.decisionId`): don't create one for it. A person-owned slot blocked on a decision is ANSWERED by them (Yes/No or a choice) — it is never closed by marking it done. **Before you recommend**, recall the user's past decisions (`synap_ask`, or find `decision` entities) so your pick follows their past choices.
+
 ### Post to the user's personal channel
 
 ```

package/skills/synap/writing-titles.md

@@ -0,0 +1,63 @@
+## Writing titles and knowledge
+
+Every write receipt runs the title rubric and returns `titleLint` when a title
+breaks it. The title is stored as you sent it — **rewrite it** (update the
+title) instead of leaving it. The pod never shortens a title for you, and over
+200 characters it refuses the write.
+
+### Title rules (every kind, every pod)
+
+1. **One complete phrase, 80 characters at most** (aim for 40–70; a question
+   may take 110). If it does not fit, rewrite it — never cut it, never end it
+   with "…".
+2. **Name the lasting thing, not the event.** No SHIPPED, LIVE, FIXED, DONE,
+   VERIFIED, CORRECTION, no emoji. Status goes in a status property; the date
+   is already on the record.
+3. **No machinery in the title:** no hashes, ids, file paths, line numbers,
+   markdown, URLs. They go in the body as evidence.
+4. **Do not repeat the kind** ("Lesson:", "Decision:", "Caution:", "Finding:").
+   The kind and `knowledgeForm` already say it.
+5. **Plain words.** A code is allowed only when the pod's glossary has it;
+   plan codes (T1, D3, W4, Wave A) are replaced by words.
+6. **Same language as the body.**
+7. **Search before you create** (`synap_ask`) and keep a title stable on
+   update. A superseded decision gets a title that says what replaced it.
+8. **Never empty, never a placeholder** ("Untitled", "Test", a URL, the first
+   words of a transcript).
+
+| Kind | Title shape | Example |
+| --- | --- | --- |
+| Knowledge | The claim as a short sentence | Space skills are linked by the brief, not by a row |
+| Decision | What was decided, as a fact | Connection data lives in one package: @synap-core/integrations |
+| Question | A real question ending in ? | Should Grida replace or complement the tldraw whiteboard? |
+| Task | Verb + object (+ who/when) | Send signed agreement to Harbor Goods |
+| Research | Subject + what was assessed | Excalidraw evaluated as a Synap capability |
+| Issue | The problem as a statement | Capture reads the URL but never feeds it to the structurer |
+| Note | What it is about | Farm-to-Client Market — idea brief |
+| Work session | The outcome, short | Frontend package consolidation: 4 layer packages |
+| Run | Run name + instance | Daily client briefing — 12 Oct |
+| Report | Scope + period | Builder weekly report — week of 5 Oct |
+
+### What counts as knowledge
+
+Knowledge is something that will **still be true and useful in three months**,
+whenever it was learned. It takes one `knowledgeForm`:
+
+- `fact` — how something works.
+- `caution` — a pitfall and how to avoid it.
+- `convention` — how we do things here.
+
+The full sentence goes in `ek_claim`; the title is its short handle, never the
+claim cut off. Everything else goes elsewhere:
+
+| It is really… | File it as |
+| --- | --- |
+| progress, "shipped", "verified", "done" | the session's outcome or report — not a lasting entity |
+| a choice that was made | `decision` |
+| an open bug or problem | `issue` |
+| a plan, an idea, a hypothesis | `note` (or `question` if it is one) |
+| steps to follow | a skill |
+| a fact about an outside tool, vendor or market | `research` |
+
+When unsure, ask: "will this still help someone in three months, and is it a
+fact, a pitfall or a rule?" If not, it is not knowledge.