@synap-core/cli 1.11.0 → 1.13.0

package/skills/synap/worked-examples.md

@@ -25,7 +25,7 @@
    { "userId": "{userId}",
      "sourceEntityId": "ent_new_task",
      "targetEntityId": "ent_acme",
-     "type": "related_to" }
+     "type": "relates_to" }
    ```
 
 5. Confirm: "Task created and linked to Acme, due Friday."
@@ -57,18 +57,17 @@
 You are authoring this text yourself — it is not a file you have. Don't create
 a `file`/`document`-kind entity and stuff the Markdown into it.
 
-1. Search for an existing plan: `GET /entities?q=Q3 launch&profileSlug=knowledge&workspaceId=…` → none
+1. Search for an existing plan: `GET /entities?q=Q3 launch&profileSlug=note&workspaceId=…` → none
 2. Create a CONTENT-kind entity carrying the plan as `content` (the doc auto-materializes):
 
    ```json
    POST /api/hub/entities
    { "userId": "{userId}", "workspaceId": "{wsId}",
-     "profileSlug": "knowledge",
+     "profileSlug": "note",
      "title": "Q3 launch strategic plan",
-     "properties": { "ek_type": "reference" },
      "content": "# Q3 Launch Plan\n\n## Goals\n…\n\n## Timeline\n…"
    }
    ```
 
-3. Link it to the relevant project: `POST /api/hub/relations` `{ sourceEntityId: "ent_new_plan", targetEntityId: "ent_project_q3", type: "related_to" }`.
+3. Link it to the relevant project: `POST /api/hub/relations` `{ sourceEntityId: "ent_new_plan", targetEntityId: "ent_project_q3", type: "relates_to" }`.
 4. Confirm: "Plan captured and linked to Q3 launch." No upload, no `file` entity, no separate `synap_create_document` call.

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** (a goal — `track` in tools), 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)   | **Goal**    | `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.
-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):
+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` — a near-duplicate name is filed for the person to review, showing the existing project; (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 lasting goal a project pursues** ("keep the content side of the launch going") → a **goal**: `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 goal), 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,11 +1,33 @@
 ## Core writes
 
-**Two write doors, one gradient.** `create_entity` is for exactly ONE
+> **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; capture-with-`entities[]` files ONE
+atomic proposal for the whole graph. Neither rejects a look-alike: a record (or
+one of your own pending proposals) of the same kind with the same name or
+identity makes the write a proposal carrying `duplicateCheck`, and the person
+decides (keep both, use the existing one, fill its empty fields). Only a strong
+identity (email, phone, url, handle, external id) links to the existing record
+on its own. 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
@@ -31,9 +53,10 @@ The response has legacy `status`/`id` fields plus `writeReceipt`:
 `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** — surface its `reviewUrl`, never
-claim completion, and only enrich again when the receipt identifies a real
-missing fact.
+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, send the whole graph through the capture door (`synap_capture` with
@@ -59,6 +82,28 @@ 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.
+
+**Removing one: `synap_delete_entity`** (`entityId`, optional `reasoning`). For an agent it is always a proposal — nothing is deleted until the person approves, and no rule can widen that. An approved delete hides the entity (its body is kept) and the person can undo it from the proposal. Do not retry a `proposed` answer.
+
 ### Authored text is content, not a `file`
 
 Something **you** author — a pitch deck, a strategic plan, a note body — is
@@ -67,8 +112,8 @@ 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 (the upload door / `synap upload`) — an agent has no filesystem, so it
-rarely touches `file` at all. Reach for `synap_create_document` /
+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`.
@@ -81,10 +126,19 @@ You CAN store content you **hold** — you send it inline. Pick by what you have
 | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
 | **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 on a local disk** you don't hold in context                                  | the CLI `synap upload <path>` (streams it) — an agent can't send bytes it doesn't have          | a `file` entity backed by stored bytes                               |
+| Only a **URL/link** (no bytes) — a Google Doc, a PDF url, an article                        | `synap_create_document` with **`url`**; `entityId` only for a thing with no body yet            | 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."
@@ -106,11 +160,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
@@ -119,35 +181,51 @@ 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}`, `set_title {title}` (renames the document, a
+human name). 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 the
+document, send a `set_title` op to `POST /api/hub/documents/{id}/patch`). 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.
 
@@ -202,6 +280,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. With no options the person sees its `title` with Accept / Reject, each saying what it does. So give it a short `title` (the decision itself, never "Decide: …") and a `summary` that says what the title does not. Only a decision YOU propose asks: a person's own proposed decision is their note, and the pod never asks them about it. 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.