create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/prime/.codex/skills/ingest/SKILL.md

@@ -1,29 +1,51 @@
 ---
 name: ingest
-description: 'Unified ingestion entry point — brings files, meetings, Google Workspace, Notion, or bulk corpora into intake, then promotes useful material into curated memory. Say ''ingest'', ''bring this into Egregore''.'
+description: "Route and run organizational ingestion through Egregore Runtime for files, folders, meetings, Google Workspace, Notion, interviews, or bulk corpora. Use for 'ingest', 'bring this into Egregore', 'index this folder', or 'import our docs'."
 ---
 
-<!-- generated-by: bin/codex-sync-skills.sh -->
-
-# Egregore ingest Adapter
-
-This is fallback coverage for a long-tail Egregore workflow that has not been
-ported to a hand-written Codex-native skill yet.
-
-Use the project shell and filesystem directly. Do not invoke Claude Code
-commands. Translate interactive choices to structured Codex question tooling
-when it is available; otherwise render compact numbered choices with an
-`Other:` option and wait for the user.
-
-1. Read `.claude/skills/ingest/SKILL.md` for the workflow details.
-2. Run the referenced `bin/` scripts directly from Codex.
-3. Treat graph and publish steps as best-effort unless that workflow explicitly
-   says they are required.
-4. For every external notification, follow
-   `.claude/context/notification-consent.md`: plan without sending, then show
-   a separate exact Send / Edit / Cancel checkpoint. Never infer notification
-   consent from the workflow request or a batch approval.
-5. Keep local-mode behavior filesystem-first and avoid graph or notification
-   calls when `egregore.json` declares `"mode": "local"`.
-6. Never call the deprecated `egregore-handoff` CLI for Egregore project
-   handoffs.
+# Ingest
+
+Keep intake separate from promotion. Route one document/URL to the add skill;
+meetings to `meeting`, interviews to `ingest-user-interview`, Google sources to
+`ingest-google`, Notion sources to `ingest-notion`, and large
+question-answering corpora to `ingest-corpus`. Keep the ingest-corpus Connected
+capability gate. For an ordinary file/folder/export, use `bin/ingest.sh`.
+
+When no path was supplied, run `bash bin/ingest.sh select`. Stop on cancel;
+route returned connectors to their skill; otherwise run:
+
+```bash
+bash bin/ingest.sh add-selection "$SELECTION_PATH"
+```
+
+For an explicit path, ask only for stable source id, visibility/sensitivity,
+hard boundaries, and whether it is an authoritative snapshot, then run:
+
+```bash
+bash bin/ingest.sh add "$PATH" --source "$SOURCE_ID" \
+  --name "$NAME" --kind "$KIND" --boundary "$KEY=$VALUE"
+```
+
+Use `--prune` only for an explicitly authoritative full snapshot. Register
+harness-produced extraction for a selected PDF only when actual normalized text
+exists:
+
+```bash
+bash bin/ingest.sh register-extraction "$SELECTION_PATH" \
+  "relative/file.pdf" --extractor "$EXTRACTOR" < normalized.txt
+```
+
+Verify with `bin/ingest.sh status` and a known-phrase search scoped to source
+and every required boundary. Report sparse/unreadable extraction and unknowns.
+
+The adapters own authorization, normalization/provenance, quarantine,
+admission, canonical registration/writeback, retrieval refresh, background
+embedding, and content-free telemetry. Do not write canonical files, run Git,
+manage retrieval implementations, query/project graph state, or repeat save or
+telemetry from this skill.
+
+Canonical Markdown/reference manifests are authoritative; local normalized
+bodies and indexes are rebuildable. Hard boundaries fail closed. Intake is not
+curated knowledge: open exact evidence and invoke the type-specific Runtime
+ritual to promote a decision, finding, research synthesis, meeting, or domain
+claim with source/chunk provenance and conflicts preserved.

package/runtime/prime/.codex/skills/ingest-user-interview/SKILL.md

@@ -1,45 +1,27 @@
 ---
 name: ingest-user-interview
-description: 'Analyze user interview transcripts (Granola, pasted text, or a file) through a 3-analyst-agent plus Opus-synthesis pipeline. Say ''process the interview'', ''onboarding interview'', ''research call''.'
+description: Analyze a Granola, pasted, or file-based user interview into an evidence-backed briefing, journey insights, product findings, patterns, and actions when the user invokes /ingest user-interview or $ingest-user-interview, or asks to process an onboarding interview, research call, or user feedback.
 ---
 
-<!-- generated-by: bin/codex-sync-skills.sh -->
+# Egregore User Interview
 
-# Egregore ingest-user-interview Adapter
+Read `references/analysis-contract.md`, acquire
+the authorized transcript source, analyze it, and show `Save / Edit / Skip`
+before writeback.
 
-This is fallback coverage for a long-tail Egregore workflow that has not been
-ported to a hand-written Codex-native skill yet.
+Reuse sufficient `EGREGORE_ORG_CONTEXT_V1`. For requested cross-interview
+comparison, make at most one Egregore retrieval request when compiled context
+is insufficient. Never call graph, QMD, Git, storage, or control-plane
+mechanics. Prefer inline analysis unless Journey, Sentiment, and Product lanes
+materially improve a long or complex interview.
 
-Use the project shell and filesystem directly. Do not invoke Claude Code
-commands. Translate interactive choices to structured Codex question tooling
-when it is available; otherwise render compact numbered choices with an
-`Other:` option and wait for the user.
+After `Save`, create one temporary `egregore-research-ingest/v1` package and
+call exactly once:
 
-## Structured UX parity
+```bash
+bash bin/research-ingest.sh interview --input "$PACKAGE_JSON"
+```
 
-This workflow has a Claude skill with user-visible structured output. After
-reading `.claude/skills/ingest-user-interview/SKILL.md`, reproduce the same visible UX in Codex:
-
-- Preserve TUI boxes, markdown tables, rich cards, browser artifact rendering,
-  exact confirmation blocks, and "no preamble" rules from the source skill.
-- Use the source skill's frame width, section order, labels, status footer,
-  and examples as the contract for the final response.
-- Never replace a required box/table/card/artifact view with a prose summary
-  unless the user explicitly asks for a summary.
-- When the source says to output a TUI box directly, paste that box as the
-  visible response, preferably in a `text` fenced block.
-- Never show raw JSON, raw command output, or unformatted script output when
-  the source skill requires formatted status or rendered output.
-
-1. Read `.claude/skills/ingest-user-interview/SKILL.md` for the workflow details.
-2. Run the referenced `bin/` scripts directly from Codex.
-3. Treat graph and publish steps as best-effort unless that workflow explicitly
-   says they are required.
-4. For every external notification, follow
-   `.claude/context/notification-consent.md`: plan without sending, then show
-   a separate exact Send / Edit / Cancel checkpoint. Never infer notification
-   consent from the workflow request or a batch approval.
-5. Keep local-mode behavior filesystem-first and avoid graph or notification
-   calls when `egregore.json` declares `"mode": "local"`.
-6. Never call the deprecated `egregore-handoff` CLI for Egregore project
-   handoffs.
+Report the Runtime receipt. Do not write canonical files, indexes, or Git
+state separately. Publication, projection, and notifications are separate
+later effects; publication and every notification require explicit approval.

package/runtime/prime/.codex/skills/ingest-user-interview/references/analysis-contract.md

@@ -0,0 +1,42 @@
+# User-interview analysis contract
+
+Start with evidence-bearing moments: friction, aha, feature gap, mental-model
+mismatch, feature discovery, suggestion, and unresolved reference. Analyze
+short interviews inline. For long or complex material, Journey, Sentiment, and
+Product lenses may run in parallel once, then synthesize their disagreements.
+
+## Briefing and insight mapping
+
+Write `# Interview Analysis: {participant} — {type} Interview` with date,
+participant, researcher, source, emotional arc, and engagement. Include the
+opinionated product reading, journey/critical path, friction and aha moments,
+discovery and mental-model mismatches, unmet needs, analytical tensions,
+evidence-backed insights, actions, and a concise participant journey note.
+
+Do not generalize one participant to all users. Every durable insight needs an
+excerpt of at most 120 characters:
+
+- friction, aha, feature gap, discovery, suggestion → `finding`;
+- mental model or cross-participant recurrence → `pattern`;
+- explicit accepted product choice → `decision`.
+
+Keep researcher commitments as actions. Show the evidence-bound preview and
+ask `Save / Edit / Skip`; Save never authorizes publication or notification.
+
+## Runtime package
+
+Create one temporary `egregore-research-ingest/v1` JSON package with:
+
+- `kind: interview`;
+- `source.type` (`granola`, `file`, or `paste`), stable `source.id`,
+  `source.revision`, and required source `content_hash`;
+- 1–40 documents with `artifact_type`, title, allowed canonical Markdown path,
+  temporary `body_path`, status/metadata, relationships, and supersedes.
+
+The briefing belongs under `research/interviews/`; optional participant
+journey material belongs under `research/participants/`; durable knowledge
+belongs under `knowledge/findings/`, `knowledge/patterns/`, or
+`knowledge/decisions/`. Runtime authorizes every artifact and path before
+reading bodies, validates the whole package, writes one Git provenance commit,
+updates retrieval once, starts one changed-hash embedding job, and emits
+content-free telemetry.

package/runtime/prime/.codex/skills/invite/SKILL.md

@@ -1,44 +1,30 @@
 ---
 name: invite
-description: Invite a GitHub user into this Egregore instance from Codex when the user invokes /invite or $invite, or asks to invite someone without exposing credentials.
+description: Invite a GitHub user into this Egregore through the authorized Runtime when the user invokes $invite or asks to invite someone.
 ---
 
-# Egregore Invite
+# Egregore invite
 
-Native Codex Egregore skill. Invite a GitHub username to the configured repos
-and, in connected mode, create the Egregore join link.
+Require one GitHub username, then run one transaction:
 
-## Flow
+```bash
+INVITE_JSON=$(bash bin/invite.sh "$ARGUMENTS")
+```
 
-1. Require a GitHub username. If missing, ask for it and stop.
-2. Read mode and config from `egregore.json`. Never print secrets from `.env`.
-3. Run credential-sensitive work in a single shell command that reads
-   `GITHUB_TOKEN` and `EGREGORE_API_KEY` internally and only prints sanitized
-   JSON.
-4. Connected mode:
-   - POST to the configured Egregore invite API with the GitHub username,
-     org, repo, slug, API key, and GitHub token.
-   - Parse the response and show invite status, memory access status, and the
-     returned invite URL.
-   - Best-effort graph record with `bin/graph.sh`.
-   - If a contact channel exists, follow
-     `.claude/context/notification-consent.md`: prepare a direct-message plan
-     and show the exact organization, recipient, channel, and message in a
-     separate Send / Edit / Cancel checkpoint. The invite request is not
-     notification consent.
-5. Local mode:
-   - Use GitHub API collaborator endpoints for the core repo, memory repo, and
-     managed repos.
-   - Create or update `memory/people/{username}.md`.
-   - Commit and push memory.
-   - Show the join command using `npx -y create-egregore@latest join`.
-6. If remote hosting is enabled, provision hosting best-effort in a detached
-   command and include the status only when it succeeds.
+The Runtime resolves and authorizes the active `ActorContext` before any
+effect. `AccountIdentity`, `ActorIdentity`, and `OrgMembership` remain
+separate; GitHub is only the current linked-provider and repository transport.
+Do not read credentials or call GitHub, the Connected API, graph, storage, or
+Git directly.
 
-## Rules
+Render the sanitized receipt: organization, repository and memory status,
+managed-repository warnings, and either the Connected invite URL or Local
+join command. Show `manual_access_url` on permission/access failure. Never
+show raw JSON or internal identity IDs.
 
-- Never expose tokens, request bodies containing tokens, or raw API JSON.
-- Only org admins can complete the connected invite flow; report API denial
-  clearly and give the manual GitHub access URL.
-- Do not use Claude Code commands.
-- Never fall back from an invite DM to a group or dispatch from detached work.
+Inviting does not authorize notification delivery. If the user separately
+wants a direct message, create a fresh `bin/notification.sh plan --kind send`
+for the exact recipient and invite URL/command, show **Send / Edit / Cancel**,
+then approve and dispatch only after fresh exact consent. Never fall back to a
+group or reuse approval.
+Notification consent and membership-invite authorization are separate.

package/runtime/prime/.codex/skills/issue/SKILL.md

@@ -1,45 +1,64 @@
 ---
 name: issue
-description: 'Report an issue — captures context and routes it to the right place. Say ''this is broken'', ''bug in'', ''file an issue'', ''report a problem''. Not a personal task (/todo) or team exploration (/quest).'
+description: "Report and manage organizational issues through Egregore Runtime. Use for 'this is broken', 'bug in', 'file an issue', 'report a problem', issue listing/search, or closing an issue; do not use for a personal todo or collaborative quest."
 ---
 
-<!-- generated-by: bin/codex-sync-skills.sh -->
-
-# Egregore issue Adapter
-
-This is fallback coverage for a long-tail Egregore workflow that has not been
-ported to a hand-written Codex-native skill yet.
-
-Use the project shell and filesystem directly. Do not invoke Claude Code
-commands. Translate interactive choices to structured Codex question tooling
-when it is available; otherwise render compact numbered choices with an
-`Other:` option and wait for the user.
-
-## Structured UX parity
-
-This workflow has a Claude skill with user-visible structured output. After
-reading `.claude/skills/issue/SKILL.md`, reproduce the same visible UX in Codex:
-
-- Preserve TUI boxes, markdown tables, rich cards, browser artifact rendering,
-  exact confirmation blocks, and "no preamble" rules from the source skill.
-- Use the source skill's frame width, section order, labels, status footer,
-  and examples as the contract for the final response.
-- Never replace a required box/table/card/artifact view with a prose summary
-  unless the user explicitly asks for a summary.
-- When the source says to output a TUI box directly, paste that box as the
-  visible response, preferably in a `text` fenced block.
-- Never show raw JSON, raw command output, or unformatted script output when
-  the source skill requires formatted status or rendered output.
-
-1. Read `.claude/skills/issue/SKILL.md` for the workflow details.
-2. Run the referenced `bin/` scripts directly from Codex.
-3. Treat graph and publish steps as best-effort unless that workflow explicitly
-   says they are required.
-4. For every external notification, follow
-   `.claude/context/notification-consent.md`: plan without sending, then show
-   a separate exact Send / Edit / Cancel checkpoint. Never infer notification
-   consent from the workflow request or a batch approval.
-5. Keep local-mode behavior filesystem-first and avoid graph or notification
-   calls when `egregore.json` declares `"mode": "local"`.
-6. Never call the deprecated `egregore-handoff` CLI for Egregore project
-   handoffs.
+# Issue
+
+Use `bin/issue.sh` as the only issue-state adapter. Canonical Markdown and Git
+are authoritative in Local and Connected modes; graph, GitHub, and notification
+systems are optional consumers.
+
+## Commands
+
+- Empty or `list` → `bash bin/issue.sh list`
+- `list open|closed|all` → `bash bin/issue.sh list --status <status>`
+- `show <id-or-title>` → `bash bin/issue.sh show "<reference>"`
+- `search <term>` → `bash bin/issue.sh search "<term>"`
+- `close <id-or-title>` → `bash bin/issue.sh close "<reference>"`
+- Anything else → derive a concise title and run one create:
+
+```bash
+bash bin/issue.sh create \
+  --title "$TITLE" --description "$DESCRIPTION" \
+  --recipient "$RECIPIENT" --topic "$TOPIC"
+```
+
+Add `--context` and `--suggested-fix` only when known. Render returned JSON as
+the established 72-column issue card; do not expose raw JSON.
+
+## Runtime contract
+
+Reuse a sufficient `EGREGORE_ORG_CONTEXT_V1`; do not repeat organizational
+retrieval. The adapter uses one authorized canonical snapshot for reads and one
+CanonicalArtifactWriteback transaction for each create/close. Do not write
+Markdown, run Git, manage retrieval indexes, query/project graph state, or
+auto-save from this skill. Age never closes an issue.
+
+## External sharing
+
+GitHub creation/closure is a distinct SHARE action. First run and display the
+exact preview:
+
+```bash
+bash bin/issue.sh share-preview "$ISSUE" --action create --repo owner/name
+bash bin/issue.sh share-preview "$ISSUE" --action close
+```
+
+Ask Send / Edit / Cancel and stop. Only after Send for the exact destination,
+title, and body/action run:
+
+```bash
+bash bin/issue.sh share-github --confirm "$CONFIRMATION_TOKEN"
+```
+
+Never call `gh issue` directly. The token expires and is bound to the unchanged
+canonical record. A successful create records its URL by canonical writeback.
+
+Notifications require another, separate consent. Follow
+`.claude/context/notification-consent.md`: plan through `bin/notify.sh`, show
+organization, recipient, channels, and exact message, then wait for one Send /
+Edit / Cancel choice. GitHub approval is not notification approval.
+
+Authorize discover/read before loading content and authorize write/share for
+each action. Graph state cannot override or block canonical issue behavior.

package/runtime/prime/.codex/skills/me/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: me
-description: 'View or change your member identity — display name, email — shared across Claude Code, Codex, and Pi. Say ''who am I'', ''call me <name>'', ''change my name to X'', or run ''/me''.'
+description: 'View or change the current member''s Egregore profile across Claude Code, Codex, Pi, and Prime. Use for /me, ''who am I'', ''call me <name>'', or an explicit self email update.'
 ---
 
 <!-- generated-by: bin/codex-sync-skills.sh -->

package/runtime/prime/.codex/skills/meeting/SKILL.md

@@ -1,45 +1,25 @@
 ---
 name: meeting
-description: 'Use for /meeting, /meeting sync, /meeting backfill, or a search term — adaptively analyzes a Granola meeting into decisions, findings, actions, and continuity in shared memory.'
+description: Analyze a Granola meeting into an evidence-backed briefing, decisions, findings, patterns, actions, and continuity when the user invokes /meeting or $meeting, asks to process meetings, sync meeting knowledge, or backfill meeting analysis.
 ---
 
-<!-- generated-by: bin/codex-sync-skills.sh -->
+# Egregore Meeting
 
-# Egregore meeting Adapter
+Read `references/analysis-contract.md`, acquire the selected
+Granola source, analyze it, and show `Save / Edit / Skip` before writeback.
 
-This is fallback coverage for a long-tail Egregore workflow that has not been
-ported to a hand-written Codex-native skill yet.
+Reuse sufficient `EGREGORE_ORG_CONTEXT_V1`; do not duplicate Observe. If
+continuity needs more evidence, use at most one Egregore retrieval request and
+open only selected canonical sources. Never call graph, QMD, Git, storage, or
+control-plane mechanics.
 
-Use the project shell and filesystem directly. Do not invoke Claude Code
-commands. Translate interactive choices to structured Codex question tooling
-when it is available; otherwise render compact numbered choices with an
-`Other:` option and wait for the user.
+After `Save`, create one temporary `egregore-research-ingest/v1` package and
+call exactly once:
 
-## Structured UX parity
+```bash
+bash bin/research-ingest.sh meeting --input "$PACKAGE_JSON"
+```
 
-This workflow has a Claude skill with user-visible structured output. After
-reading `.claude/skills/meeting/SKILL.md`, reproduce the same visible UX in Codex:
-
-- Preserve TUI boxes, markdown tables, rich cards, browser artifact rendering,
-  exact confirmation blocks, and "no preamble" rules from the source skill.
-- Use the source skill's frame width, section order, labels, status footer,
-  and examples as the contract for the final response.
-- Never replace a required box/table/card/artifact view with a prose summary
-  unless the user explicitly asks for a summary.
-- When the source says to output a TUI box directly, paste that box as the
-  visible response, preferably in a `text` fenced block.
-- Never show raw JSON, raw command output, or unformatted script output when
-  the source skill requires formatted status or rendered output.
-
-1. Read `.claude/skills/meeting/SKILL.md` for the workflow details.
-2. Run the referenced `bin/` scripts directly from Codex.
-3. Treat graph and publish steps as best-effort unless that workflow explicitly
-   says they are required.
-4. For every external notification, follow
-   `.claude/context/notification-consent.md`: plan without sending, then show
-   a separate exact Send / Edit / Cancel checkpoint. Never infer notification
-   consent from the workflow request or a batch approval.
-5. Keep local-mode behavior filesystem-first and avoid graph or notification
-   calls when `egregore.json` declares `"mode": "local"`.
-6. Never call the deprecated `egregore-handoff` CLI for Egregore project
-   handoffs.
+Report the Runtime receipt. Do not write canonical files or run `/save`
+separately. Publication, projection, and notifications are separate later
+effects; publication and every notification require explicit approval.

package/runtime/prime/.codex/skills/meeting/references/analysis-contract.md

@@ -0,0 +1,48 @@
+# Meeting analysis contract
+
+Use only the lenses that serve the user's intent and the material:
+
+- Substance: decisions, findings, patterns, actions, dependencies, evidence,
+  tradeoffs, confidence, and open questions.
+- Dynamics: tone arc, conviction, alignment, divergence, and energy shifts.
+- Continuity: what changed, repeated, resolved, superseded, or disappeared.
+- Criticality: unnamed risks and gaps between stated confidence, behavior, and
+  organizational reality.
+
+Inline analysis is the fast default. Parallel analysts are justified only for
+long or genuinely complex material.
+
+## Briefing and extracted knowledge
+
+Write `# Meeting Intelligence: {title}` with source/date/attendees, approach,
+and user intent. Include only useful analysis: the heart and genuinely new
+information; actuality against current canonical context; dynamics and
+convictions when applied; priorities/dependencies; evolution and tensions;
+actions; and unresolved threads.
+
+Persist only durable `decision`, `finding`, or `pattern` documents. Preserve
+context, rationale, tradeoffs, calibrated confidence, speaker, an evidence
+excerpt of at most 120 characters, topics, open questions, urgency, and
+explicit supersession/relationships. Actions stay separate. Never preserve
+small talk, logistics, or unsupported claims.
+
+Show a compact evidence-bound preview and ask `Save / Edit / Skip`. Save is
+canonical writeback consent only, never publication or notification consent.
+
+## Runtime package
+
+Create one temporary `egregore-research-ingest/v1` JSON package with:
+
+- `kind: meeting`;
+- `source.type`, stable `source.id`, `source.revision`, required source
+  `content_hash`, and optional `source.uri`;
+- 1–40 documents with `artifact_type`, title, allowed canonical Markdown path,
+  temporary `body_path`, status/metadata, relationships, and supersedes.
+
+The meeting briefing belongs under `meetings/`; durable extracted knowledge
+belongs under `knowledge/decisions/`, `knowledge/findings/`, or
+`knowledge/patterns/`. Body paths are temporary analysis outputs, never direct
+canonical writes. Runtime authorizes every artifact and path before reading
+bodies, validates the complete package, writes one Git provenance commit,
+updates retrieval once, starts one changed-hash embedding job, and emits
+content-free telemetry.

package/runtime/prime/.codex/skills/note/SKILL.md

@@ -1,29 +1,34 @@
 ---
 name: note
-description: 'Use when the user says ''jot this down'', ''note to self'', ''just thinking out loud'', or ''park this thought'' — saves a private personal note, never shared or pushed until explicitly promoted.'
+description: "Use when the user says 'jot this down', 'note to self', 'just thinking out loud', or 'park this thought' — saves an actor-owned private draft locally and promotes it to organizational knowledge only on explicit request."
 ---
 
-<!-- generated-by: bin/codex-sync-skills.sh -->
-
-# Egregore note Adapter
-
-This is fallback coverage for a long-tail Egregore workflow that has not been
-ported to a hand-written Codex-native skill yet.
-
-Use the project shell and filesystem directly. Do not invoke Claude Code
-commands. Translate interactive choices to structured Codex question tooling
-when it is available; otherwise render compact numbered choices with an
-`Other:` option and wait for the user.
-
-1. Read `.claude/skills/note/SKILL.md` for the workflow details.
-2. Run the referenced `bin/` scripts directly from Codex.
-3. Treat graph and publish steps as best-effort unless that workflow explicitly
-   says they are required.
-4. For every external notification, follow
-   `.claude/context/notification-consent.md`: plan without sending, then show
-   a separate exact Send / Edit / Cancel checkpoint. Never infer notification
-   consent from the workflow request or a batch approval.
-5. Keep local-mode behavior filesystem-first and avoid graph or notification
-   calls when `egregore.json` declares `"mode": "local"`.
-6. Never call the deprecated `egregore-handoff` CLI for Egregore project
-   handoffs.
+# Note
+
+Treat the thought as private, half-baked actor state. Capture it with one call:
+
+```bash
+bash bin/knowledge.sh note-create --title "{title}" \
+  --type "{thought|session|retrospective|journal}" --input "$TMP_NOTE"
+```
+
+Use `bash bin/knowledge.sh note-list` to list and
+`bash bin/knowledge.sh note-open "{path}"` to open an actor-authorized note.
+Private notes are not canonical organizational truth and are not committed,
+indexed, published, shared, or notified.
+
+For `share` or `promote`, preview the selected note, choose `decision`,
+`finding`, or `pattern`, and wait for explicit approval. Then call:
+
+```bash
+bash bin/knowledge.sh note-promote --path "{path}" --type "{type}" \
+  --title "{title}" --topic "{topic}" --workstream "{workstream}"
+```
+
+Promotion enters CanonicalArtifactWriteback with typed source provenance; the
+private copy remains and records its canonical target. Policy hints describe
+private posture but never authorize access.
+
+Do not call Git, QMD, graph, control-plane storage, telemetry, publishing,
+sharing, or notification mechanics directly. Promotion is not external
+publication; external effects require separate permission and explicit consent.