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

package/runtime/codex/.codex/skills/archive/SKILL.md

@@ -1,45 +1,30 @@
 ---
 name: archive
-description: 'Capture an effective prompting technique or steering pattern as reusable knowledge. Use for /archive, or when a prompt worked especially well and is worth reusing — not insight about the work itself (/reflect).'
+description: "Capture an effective prompting or steering technique as a reusable canonical pattern. Use when a prompt chain worked especially well; use $reflect for work insights and $note for private thoughts."
 ---
 
-<!-- generated-by: bin/codex-sync-skills.sh -->
+# Archive
 
-# Egregore archive Adapter
+Extract a reusable steering chain from the session or the user's description.
+Record each move's type, trigger, intervention, effect, and principle, plus the
+chain's when-to-use guidance and outcome. Reuse attached
+`EGREGORE_ORG_CONTEXT_V1`; retrieve once only for a named gap or likely
+duplicate, and open exact evidence through `bin/search.sh`.
 
-This is fallback coverage for a long-tail Egregore workflow that has not been
-ported to a hand-written Codex-native skill yet.
+Show the proposed chain and wait for acceptance or edits. Render the accepted
+body to a temporary file, then call exactly once:
 
-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.
+```bash
+bash bin/knowledge.sh create --type pattern --subtype prompt-chain \
+  --title "{chain name}" --input "$TMP_ARTIFACT" \
+  --topic prompt-chain --topic "{topic}" --workstream "{workstream}"
+```
 
-## Structured UX parity
+This Runtime command owns ActorContext authorization, stable identity and
+provenance, canonical Markdown, Git provenance, retrieval refresh, background
+embedding, and content-free telemetry. Add relationships only when explicit.
 
-This workflow has a Claude skill with user-visible structured output. After
-reading `.claude/skills/archive/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/archive/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.
+Do not call Git, QMD, graph, control-plane storage, telemetry, publishing,
+sharing, or notification mechanics directly. Graph is optional and advisory;
+canonical Markdown wins. External effects require separate permission and
+explicit consent. Report the canonical path and writeback status.

package/runtime/codex/.codex/skills/checkup/SKILL.md

@@ -1,45 +1,86 @@
 ---
 name: checkup
-description: 'Run diagnostics on your Egregore environment and render a health report, auto-fixing what it can. Use for /checkup, a health check, or when something is broken and the root cause is unclear.'
+description: 'Run diagnostics on an Egregore environment and render a health report, repairing safe local Runtime problems when possible. Use for $checkup, a health check, or when something is broken and the root cause is unclear.'
 ---
 
-<!-- generated-by: bin/codex-sync-skills.sh -->
+# Egregore checkup
 
-# Egregore checkup Adapter
+Native Codex Egregore skill. Diagnose canonical Egregore Runtime health before
+optional integrations. Do not invoke Claude commands or read QMD internals.
 
-This is fallback coverage for a long-tail Egregore workflow that has not been
-ported to a hand-written Codex-native skill yet.
+## Structured UX parity
 
-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.
+Render the same compact `⊕ CHECKUP` box as the Claude surface: `CONFIG`,
+`RUNTIME`, optional `CONNECTED INTEGRATIONS`, then `WORKSPACE`. Preserve the
+separate Runtime and integration verdicts; never expose raw JSON or probe
+output.
 
-## Structured UX parity
+## Procedure
+
+Detect mode from `egregore.json`. Treat an explicit local mode or absent
+`api_url` as local. Run three sequential batches so network timeouts cannot
+obscure local health.
+
+### 1. Canonical Runtime
+
+Read the typed Runtime health surface once:
+
+```bash
+EGREGORE_ROOT="$PWD" PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" \
+  python3 -m egregore_runtime.harness_cli status --json
+```
+
+Interpret only the returned contract:
+
+- `canonical_state_ready` is foundational.
+- `adapter=qmd-local`, `collection`, and `index_path` identify the
+  instance-owned Local Retriever.
+- `runtime_state`, `runtime_pid`, and `runtime_endpoint` report owned worker
+  readiness.
+- `bm25_ready`, `semantic_ready`, and `embedding_state` distinguish ready,
+  lexical fallback, and warming states.
+- `index_spec_version`, `index_revision`, and `source_revision` report
+  freshness.
+
+Never invoke `qmd`, inspect process tables, guess a port, or inspect another
+instance's runtime directory. If canonical memory is ready but the owned worker
+or index is unavailable, run `bash bin/search.sh start` once and re-read the
+same Runtime health surface once. Semantic warming is a warning, not data loss.
+
+Validate `egregore.json`, the `memory` link/repository, and only the required
+key names in `.env`; never print secret values.
+
+### 2. Connected integrations
+
+Skip entirely in local mode. In connected mode, run graph/control-plane and
+notification probes with ten-second timeouts:
+
+```bash
+timeout 10 bash bin/graph-projection.sh verify --enable 2>&1; echo "EXIT:$?"
+timeout 10 bash bin/notification.sh status 2>&1; echo "EXIT:$?"
+```
+
+Classify graph/control-plane failures as Connected integration warnings;
+canonical Markdown remains authoritative. Read the notification Runtime's
+sanitized JSON `status` field:
+`ok` (connected) or `configured` (local) is healthy. Never replace API keys,
+repair projections, send notifications, or publish from checkup.
+
+### 3. Workspace
+
+Check the configured base branch, current worktree, memory repository, local
+framework version, and any configured launcher. Do not fetch, pull, commit,
+push, publish, or mutate canonical memory. Offer `$pull`, `$update`, or `$setup`
+as Egregore next actions when needed.
+
+## Report
+
+Use `✓`, `⚠`, and `✗`. In local mode omit `CONNECTED INTEGRATIONS`. End with:
+
+```text
+Runtime {ready|degraded|unavailable} · {N} warnings · integrations {state}
+```
 
-This workflow has a Claude skill with user-visible structured output. After
-reading `.claude/skills/checkup/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/checkup/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.
+Derive Runtime readiness from canonical/Local Retriever state, never from
+Graph, control-plane, or Telegram health. Emit telemetry only through the
+normal command wrapper, best-effort.

package/runtime/codex/.codex/skills/dark-mode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dark-mode
-description: 'Use when generating or modifying any visual output that renders in a browser or artifact viewer: HTML pages, CSS, React SSR components, Egregore artifacts, markdown renderers, web components, design-system tokens, Tailwind themes, or standalone demos. Triggers on requests involving dark mode, theme toggles, color systems, card surfaces, browser rendering, or visual polish. The load-bearing lesson: if React SSR emits an inline hex color through `style={}`, CSS dark-mode overrides cannot reach it, so every theme-sensitive color must be emitted as `var(--token)` rather than a resolved hex. Do not use for TUI output, plain markdown files, or non-visual code.'
+description: 'Use when authoring or modifying browser-rendered visual output: HTML, CSS, React SSR, artifact templates, markdown renderers, design tokens, themes, or composed pages. Do not invoke for an ordinary /view render—the checked-in renderer already owns its theme contract. The load-bearing rule is that theme-sensitive colors must be emitted as `var(--token)`, never resolved inline hex.'
 ---
 
 <!-- generated-by: bin/codex-sync-skills.sh -->

package/runtime/codex/.codex/skills/dashboard/SKILL.md

@@ -1,59 +1,29 @@
 ---
 name: dashboard
-description: Show the current user's Egregore dashboard, recent sessions, open threads, and current work from Codex when the user invokes /dashboard or $dashboard, or asks for their dashboard.
+description: Explicit personal-status surface for /dashboard, $dashboard, or a direct request for the whole personal overview. Do not use it to find or resume one specific prior handoff, project, or work thread; that is semantic organizational recall through Runtime/QMD.
 ---
 
 # Egregore Dashboard
 
-Native Codex Egregore skill. Render the personal dashboard immediately from
-`bin/dashboard-data.sh` and the shared renderer.
+Use this bounded status card only when the user explicitly asks for Dashboard
+or the whole personal overview. A request to return to one earlier piece of
+work must use attached `EGREGORE_ORG_CONTEXT_V1` evidence or exactly one Search
+workflow query when that evidence is absent. Never use Dashboard as discovery
+fallback.
 
-## Flow
-
-1. Map user range words to ISO-ish ranges:
-   - empty or `week` -> `P7D`
-   - `today` -> `P1D`
-   - `month` -> `P30D`
-   - `all` -> `P365D`
-2. Run `bash bin/dashboard-data.sh "" "$TIME_RANGE"` with network escalation
-   and capture stdout as JSON. This command performs the graph API call
-   internally; a normal sandboxed Codex shell can make a healthy graph look
-   unreachable.
-3. Classify graph status:
-
-```bash
-node bin/codex-skill-render.mjs classify-graph --mode connected
-```
-
-If the network-enabled command still returns `retry` because the reason is
-`unreachable`, render the filesystem fallback and mention that the graph service
-was unreachable after a network-enabled attempt. If network escalation is denied
-or unavailable, run the command without escalation, render the fallback, and
-say Codex graph network access was not granted; do not claim the graph itself
-was unreachable.
-
-4. Render:
+Map the range to `P1D`, `P7D`, `P30D`, or `P365D`, then fetch and render one
+authorized Runtime snapshot:
 
 ```bash
-node bin/codex-skill-render.mjs dashboard-card <json-file>
+bash bin/dashboard-data.sh "$TIME_RANGE" 2>/dev/null \
+  | bash bin/node-run.sh bin/codex-skill-render.mjs dashboard-card -
 ```
 
-Paste the rendered card exactly in the visible response, preferably in a
-`text` fenced block. Do not paraphrase the card into bullets unless the user
-asks for a summary.
-
-5. End with a compact next-action prompt. Use structured Codex question
-   tooling when available; otherwise render numbered choices plus `Other:`.
-
-## Rules
+Paste the card exactly and stop. Never expose raw JSON, sync repositories, or
+call QMD, graph, GitHub, Supabase, or a control-plane API. Canonical Markdown
+and Runtime lifecycle state are authoritative.
 
-- Never show raw JSON.
-- Do not narrate each command step unless something blocks the workflow; the
-  final visible response should lead with the rendered card.
-- Structured UX parity is required: preserve the rendered dashboard TUI card,
-  no preamble, no prose-only replacement, and no raw collector output.
-- Do not call `bin/graph.sh` directly; `bin/dashboard-data.sh` is the data
-  boundary.
-- In local mode, do not mention graph setup; memory files are the source of
-  truth.
-- Do not use Claude Code commands.
+Connected enrichment is optional and explicit: set
+`EGREGORE_STATUS_CONNECTED_ENRICH=1` only when the user asks for projected
+Connected status. It is capability/permission gated and cannot override the
+canonical snapshot.

package/runtime/codex/.codex/skills/handoff/SKILL.md

@@ -1,166 +1,117 @@
 ---
 name: handoff
-description: Create an internal Egregore team handoff when the user invokes /handoff or $handoff, asks to hand off work, or wants to pass context to a teammate or future self.
+description: Create an internal Egregore team handoff when the user invokes /handoff or $handoff, asks to pass work or context, or wants an operational continuation record for a teammate or future self. Route external or executable capsules to $emissary.
 ---
 
-# Egregore Handoff
-
-Native Codex Egregore skill. This creates an internal team handoff in
-`memory/handoffs/`, indexes it, publishes it when possible, and may prepare an
-external notification proposal. External runnable packets are emissaries; if the user
-asks for one or provides an `egregore.xyz/emissary/e/` link, use the emissary
-tooling instead.
-
-`/handoff` is pure addressed capture. Do not triage incoming handoffs here;
-route “show/close my handoffs” to `$activity`. Personal session closure without
-an addressed recipient belongs to `$wrap`.
-
-## Flow
-
-1. Run `bin/agent.sh sync`.
-2. Resolve the author from `.egregore-state.json` `github_username`, then
-   `name`, then git config.
-3. Parse a short topic and optional recipient from the user request. Match the
-   recipient against `memory/people/*.md`; omit the recipient when uncertain.
-4. Classify the content before drafting:
-   - **Supplied content**: the user pasted substantial prose, supplied a
-     document, or approved exact wording. Preserve wording, order, headings,
-     lists, code, and links. Add only capture frontmatter with
-     `content_mode: supplied`. Do not create a composed JSON or attach session
-     artifacts unless the user asks.
-   - **Generated content**: the user supplied only a topic or fragmentary
-     notes. Draft the canonical markdown record with these sections:
-     - `## Briefing`
-     - `## Key Decisions`
-     - `## Current State`
-     - `## Open Threads`
-     - `## Next Steps`
-     - `## Entry Points`
-   Use this metadata contract even when the user supplied only prose:
+# Egregore handoff
+
+Create one typed handoff in `memory/handoffs/`. Canonical Markdown and Git
+provenance are authoritative. Runtime owns authorization, stable identity,
+persistence, provenance, retrieval refresh, background embedding, and
+content-free telemetry.
+
+Use this only for internal handoffs. Route external capsules to `$emissary`,
+pending-work triage to `$activity`, and personal closure to `$wrap`.
+
+## Bounded capture
+
+A handoff records known context; it is not a research, audit, planning, or
+verification ritual.
+
+- Use the user's prompt, current conversation, and attached
+  `EGREGORE_ORG_CONTEXT_V1`. When that context is attached, do not repeat
+  organizational retrieval.
+- If no organizational context is attached and the requested handoff
+  semantically depends on prior organizational work that is absent from the
+  conversation, follow the actor context's one Runtime/QMD recall instruction.
+  This is the only allowed retrieval: use its returned evidence without a
+  second query or opening more sources.
+- Do not otherwise search, inspect Git, read repository files, query
+  migration/skill manifests, run status/tests, or spawn agents to improve the
+  handoff.
+- Include branches, files, decisions, tests, and remaining work only when
+  already known from those inputs. Label uncertainty briefly; if the handoff
+  cannot be drafted responsibly, ask one focused question instead of exploring.
+- “To myself” resolves to `Actor display name` in the attached
+  `EGREGORE_ACTOR_CONTEXT_V1`. Never infer it from the OS username, Git, or
+  GitHub. If that block is unavailable, ask for the handle rather than
+  guessing. Do not perform a people-directory lookup. Ask once only for a
+  genuinely ambiguous teammate.
+- Infer `intent`: `action`, `feedback`, or `fyi`.
+
+Before approval, use at most one optional Runtime/QMD recall command, followed
+by the preview command below.
+After approval, use exactly one shell command: writeback plus card rendering.
+Do not perform notification or publication work unless separately requested.
+
+## Canonical Markdown
+
+Use this envelope:
 
 ```markdown
 ---
 capture_schema: egregore-capture/v1
 capture_mode: addressed
 kind: addressed
-from: <author>
-addressed_to: <recipient, if any>
+from: <actor handle>
+addressed_to: <recipient, if known>
 date: YYYY-MM-DD
 topic: <topic>
 intent: <action | feedback | fyi>
 content_mode: <supplied | generated>
-claim: <one-line claim>
+claim: <one-line current state>
 ask: <what the receiver should do>
 ---
-```
-
-5. Build the preview. For supplied content, render the Markdown directly
-   through the native handoff renderer and verify fidelity:
-
-```bash
-node packages/egregore-artifacts/bin/cli.js handoff "$BODY_FILE" \
-  --verify-fidelity
-```
-
-   For generated content, compose the HTML view from that record. Markdown is
-   canonical; the JSON is
-   only a presentation map. Give every JSON section a stable `id` and add a
-   top-level `sourceMap` from every authored `##` heading to the section that
-   contains its complete text:
-
-```json
-{
-  "kind": "handoff",
-  "kicker": "Handoff",
-  "topic": "<topic>",
-  "claim": "<one-line claim>",
-  "sourceMap": {
-    "Briefing": "briefing",
-    "Key Decisions": "decisions",
-    "Current State": "current-state",
-    "Open Threads": "open-threads",
-    "Next Steps": "next-steps",
-    "Entry Points": "entry-points"
-  },
-  "sections": [
-    {"id":"briefing","label":"Briefing","component":"prose","body":"<complete Briefing text>"}
-  ]
-}
-```
 
-   Pick richer components when they fit, but copy all authored content into
-   the mapped destination. Never independently summarize the Markdown into the
-   JSON. For command-heavy sections, keep command headings, explanatory text,
-   fenced commands, and expected output verbatim.
-
-   Render generated content with semantic coverage enabled:
-
-```bash
-node packages/egregore-artifacts/bin/cli.js composed "$COMPOSED_FILE" \
-  --source "$BODY_FILE" --verify-fidelity
+<canonical handoff body>
 ```
 
-6. Show the actual browser HTML before publishing. This is the approval
-   surface—not a list of component names.
+Preserve supplied wording, order, headings, lists, code, and links. For
+generated content, use only the useful subset of Briefing, Current State, Open
+Threads, and Next Steps. Keep it operational and concise.
 
-   Stop for confirmation after the browser preview. If validation fails, fix
-   the mapping/content and render again. Skip confirmation only when the user
-   explicitly said to send without preview.
+## One-command preview
 
-7. After confirmation, run one orchestration command:
+Pipe the exact canonical Markdown once to the private preview bridge. It stores
+the approved bytes in an OS-private, short-lived record and returns an opaque
+`HANDOFF_PREVIEW_TOKEN`. Retain that token for the approval turn. Do not create
+checkout or draft files yourself. The bridge renders with `--verify-fidelity`.
+If the renderer reports that its local dependencies are missing, stop and
+report that prerequisite. Never install packages or repeat the full preview
+command inside the handoff workflow.
 
 ```bash
-TMPDIR="$(mktemp -d -t codex-handoff-XXXXXX)"
-TMPDIR="$TMPDIR" bash bin/capture-run.sh --mode addressed --author "$AUTHOR" \
-  --topic "$TOPIC" ${RECIPIENT_ARG} --content-mode "$CONTENT_MODE" \
-  ${COMPOSED_ARG} < "$BODY_FILE"
+bash bin/handoff-preview.sh preview \
+  --author "$AUTHOR" --recipient "$RECIPIENT" --topic "$TOPIC" \
+  --intent "$INTENT" --content-mode "$CONTENT_MODE" <<'EGREGORE_HANDOFF'
+<exact canonical Markdown>
+EGREGORE_HANDOFF
 ```
 
-Use `COMPOSED_ARG=(--composed "$COMPOSED_FILE")` only for generated content.
+Show the browser preview and wait for approval unless explicitly waived.
+Preview is not canonical writeback. Preview approval is not sharing consent.
 
-Use `--recipient "$RECIPIENT"` only when a clear teammate or future-self
-recipient is known. Do not pass `--no-publish` unless the user explicitly
-asked for a dry run. The runner may plan a notification, but never dispatches.
+## One-command approval
 
-8. Read `$TMPDIR/handoff-run-result.json` and render:
+After approval, submit only the opaque token returned by preview. Never replay,
+regenerate, or include the canonical Markdown in the approval command. The
+bridge consumes the exact previewed bytes, performs one Runtime transaction,
+and renders the deterministic result card in the same invocation:
 
 ```bash
-node bin/codex-skill-render.mjs handoff-card "$TMPDIR/handoff-run-result.json"
+bash bin/handoff-preview.sh approve "<HANDOFF_PREVIEW_TOKEN>"
 ```
 
-Paste the rendered card exactly in the visible response, preferably in a
-`text` fenced block. Do not paraphrase the card into bullets unless the user
-asks for a summary.
-
-9. If the result has `notifyStatus: "approval_required"`, follow
-   `.claude/context/notification-consent.md`. In a separate checkpoint, show
-   the exact organization, recipient/group, every channel/delivery, and exact
-   message from `notifyPlan`; offer Send / Edit / Cancel and wait. Only a Send
-   response to that preview permits one `approve` + `dispatch`. A local direct
-   message never falls back to a group.
+The token is private, expires after six hours, and is consumed after a
+successful canonical write. Do not add a cleanup trap or recursive deletion to
+the approved command; the bridge manages only its exact private records.
 
-10. Fire the detached save helper when appropriate:
-
-```bash
-( bash bin/handoff-save-egregore.sh "$AUTHOR" "$TOPIC" >/dev/null 2>&1 & ) >/dev/null 2>&1
-```
+Omit `--recipient` from the preview command only for an unaddressed
+continuation. Runtime performs authorize → canonical persist → Git provenance
+→ retrieval update → background embed → telemetry. Return the card verbatim
+and canonical `memory/...` path. Do not print raw JSON. Do not run a second save
+or manage Git, QMD, graph, publication, or notification.
 
-11. Report the `memory/...` path and hosted link from the result JSON when a
-   link exists.
-
-## Rules
-
-- Do not call `egregore-handoff` for project handoffs.
-- Do not use Claude Code commands.
-- Keep the briefing concise and operational; include exact files, branches,
-  commands, open questions, and verification state when relevant.
-- Supplied content is authoritative. Do not replace it with a session summary,
-  presentation JSON, related artifacts, or repo state.
-- The artifact is a view of the handoff, never a summary of it. Publishing
-  must fail when any non-empty authored section is unmapped or loses content.
-- Structured UX parity is required: the rendered card is the acknowledgment.
-  Do not add a preamble such as "Handoff created successfully." Preserve the
-  72-column TUI/card shape, status footer, links below the box, and warning
-  placement used by the Egregore handoff workflow.
-- Creating or approving the handoff is not notification consent. Never approve
-  or dispatch from detached work.
+If writeback fails, report the concise error and stop. External sharing is a
+separate `SHARE` action requiring an explicit user request and exact
+destination/payload approval.