@c4a/context-cli 0.6.1 → 0.6.3

package/providers/context/provider.yaml

@@ -0,0 +1,12 @@
+schema: agent-graph.provider.v1
+id: c4a/context
+version: 0.6.3
+name: Context workflow
+description: Internal work contract for Context knowledge workspaces.
+graphs:
+  - graphs/workspace.yaml
+catalogs:
+  codes: codes.yaml
+compatibility:
+  agentGraph: ^0.2.2
+  node: ">=20"

package/providers/context/resources/diagnostics/projection-stale.md

@@ -0,0 +1,13 @@
+---
+schema: agent-graph.resource.v1
+id: diagnostic.projection-stale
+kind: diagnostic
+mediaType: text/markdown
+---
+
+# Approved projection is stale
+
+Approved Markdown changed successfully. Its derived `knowledge/structure.yaml`
+projection has not been rebuilt yet. Run only the revision-bound close command
+selected by the current Route. This is an expected lifecycle transition, not a
+content verification failure.

package/providers/context/resources/diagnostics/verification.md

@@ -0,0 +1,21 @@
+---
+id: diagnostic.verification
+kind: diagnostic
+mediaType: text/markdown
+---
+
+# Verification diagnostics
+
+Context reports one root diagnostic with counts and keeps derived findings in a
+separate detail view. Codes are stable machine identifiers; this document gives
+the shared recovery boundary.
+
+Content or provenance failures require a new source-bound candidate or an
+explicit evidence-maintenance decision. Projection-only failures can be
+repaired by deterministic close. A warning does not become success by being
+omitted from output.
+
+`approved-source-orphaned` is a persistent warning produced only after an
+explicit `keep-orphaned` decision. It records that the page remains usable by
+policy while its original source document cannot be resolved. It does not
+permit changed source content to bypass replacement Review.

package/providers/context/resources/diagnostics/workspace-state.md

@@ -0,0 +1,27 @@
+---
+id: diagnostic.workspace-state
+kind: diagnostic
+mediaType: text/markdown
+---
+
+# Invalid workspace state
+
+This route means Context could observe the workspace but could not prove a
+legal lifecycle action from its facts.
+
+Read the root diagnostics and their structured details. Repair the named
+project declaration or missing lifecycle artifact. Do not rerun completed
+phases, edit generated `knowledge/structure.yaml`, or delete runtime state as a
+shortcut.
+
+If the diagnostic reports a route/fact conflict, preserve the status output and
+stop lifecycle writes until the conflict is resolved.
+
+`diagnostic.compile-route-ambiguous` means project declarations assign more
+than one compile phase to the same source and collection. Make that ownership
+unique in `src/index.ts`; verification cannot choose one for you.
+
+`diagnostic.structure-snapshot-missing` means a persisted compile batch names a
+confirmed structure digest whose snapshot is absent. Restore that snapshot, or
+declare and confirm a new structure round for the affected source and
+collection. Do not edit digest fields to silence the diagnostic.

package/providers/context/resources/dialogue/code-extraction.md

@@ -0,0 +1,34 @@
+---
+id: dialogue.code-extraction
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code-extraction dialogue
+
+Describe the proposed code scope before SDK fields. State:
+
+- the confirmed repository module;
+- which files are included;
+- whether extraction follows configured/public entries or scans all matched
+  files;
+- whether internal symbols are included; and
+- that the first run or later deltas produce Review candidates rather than
+  approved Markdown.
+
+If a selected package lacks a standard entry, offer two Context-owned choices:
+configure source-relative API roots, or use scan mode for all declarations in
+the confirmed file scope. Do not ask the user to change source code or package
+metadata to satisfy Context.
+
+Run the route-selected dry-run first. Report discovered, AST-analyzed, skipped,
+symbol, relation, and candidate counts separately, plus resolved entries,
+exported/internal counts, symbol-kind counts, and the proposed knowledge tree.
+Treat those fields as structural scope evidence, not a semantic ranking. Stop
+when the preview crosses the confirmed module boundary or the module
+identity/path shape is wrong.
+
+For a multi-module round, finish every pending extraction target before opening
+one Review. For an unchanged repeat run, explain that no added, changed, or
+removed symbols need a decision. Mention `extractTs`, `include`, `entries`,
+`mode`, or `exportedOnly` only in technical configuration detail.

package/providers/context/resources/dialogue/document-capture.md

@@ -0,0 +1,29 @@
+---
+id: dialogue.document-capture
+kind: procedure
+mediaType: text/markdown
+---
+
+# Document-capture dialogue
+
+Registration records a document boundary but does not read its body. Before the
+capture gate is resolved, explain that capture will:
+
+- read only the registered local or remote module;
+- write a normalized committed snapshot under the date directory;
+- update that date directory's shared `manifest.json`; and
+- provide offline evidence for Review, verify, and fresh-clone reproduction.
+
+For remote documents, credentials stay in the external document client and are
+not written to the workspace. Several requested documents may share the date,
+while each retains its own module and snapshot identity.
+
+Ask for permission to read the exact pending modules. Do not run capture,
+refresh, or capture preview before permission is clear. A request that
+explicitly says to ingest, fetch, capture, or read the named documents grants
+that scope; merely mentioning a possible source does not.
+
+If deterministic inspection detects `.mdx`, route metadata, sidebars, or a docs
+configuration, explain that the boundary looks like a documentation site and
+ask whether to use the Context document-site processor. Do not infer that
+choice from filenames alone.

package/providers/context/resources/dialogue/document-classification.md

@@ -0,0 +1,33 @@
+---
+id: dialogue.document-classification
+kind: procedure
+mediaType: text/markdown
+---
+
+# Document-classification dialogue
+
+Do not recommend a collection before reading the collection-neutral evidence
+view and every required source-body resource. Summarize the observed document
+shape, explain one evidence-backed
+recommendation, and describe its package root:
+
+| Collection | Use when the evidence primarily represents | Package root |
+|---|---|---|
+| `business` | business domains, actors, objects, and non-technical domain knowledge | `wikis/` |
+| `product` | requirements, user behavior, user stories, and acceptance intent | `wikis/` |
+| `architecture` | system structure, module design, technical mechanisms, and platform/tooling design | `guides/` |
+| `sop` | procedures, runbooks, operations, maintenance, and troubleshooting steps | `guides/` |
+| `faq` | question-and-answer material intended for issue-oriented retrieval | `guides/` |
+| `standards` | normative rules, constraints, checklists, and quality/compliance requirements | `rules/` |
+| `decision` | explicit alternatives, selected choices, trade-offs, and decision records | `guides/` |
+| `incident` | incident timelines, impact, causes, response, and prevention | `guides/` |
+| `test` | test plans, validation scenarios, matrices, and acceptance cases | `rules/` |
+
+`codegraph` comes from code extraction and `feats` is not a document mainline
+collection. Filenames, URLs, titles, and example collection names are
+insufficient evidence.
+
+Ask the user to confirm exactly one mainline collection for the current source,
+unless session-managed authority resolves this gate. After confirmation,
+declare the complete align, compile, and Review lifecycle for the same source
+and collection, then re-evaluate because other captured targets may remain.

package/providers/context/resources/dialogue/evidence-maintenance.md

@@ -0,0 +1,26 @@
+---
+id: dialogue.evidence-maintenance
+kind: procedure
+mediaType: text/markdown
+---
+
+# Evidence-maintenance dialogue
+
+Explain that approved content remains present but its current source evidence
+has changed.
+
+For stale evidence, offer:
+
+- create an updated Review candidate when facts, wording, or scope may have
+  changed; or
+- re-pin the existing page only when the content is still valid and the change
+  is purely locational or otherwise body-neutral.
+
+For orphaned evidence, offer:
+
+- deprecate the page so later packages stop selecting it while audit history is
+  retained; or
+- keep it as source-orphaned knowledge with an explicit continuing warning.
+
+Do not describe re-pin as content refresh, and do not target maintenance by a
+guessed file path. Use the current diagnostic's exact `view_ref`.

package/providers/context/resources/dialogue/human-gates.md

@@ -0,0 +1,34 @@
+---
+id: dialogue.human-gates
+kind: procedure
+mediaType: text/markdown
+---
+
+# Human-gate dialogue
+
+Explain the user decision before implementation detail. State:
+
+- what is being decided;
+- what changes after confirmation;
+- which source boundary, knowledge shape, or output is affected; and
+- which meaningful alternatives exist.
+
+Use the user's conversation language. Keep commands, paths, ids, status values,
+payload keys, and `source_ref` values exact.
+
+When two or three fixed choices exist, prefer the host's native choice UI. If
+none is available, present concise A/B/C choices with one impact sentence each.
+Labels must describe user outcomes, not SDK factories or internal route names.
+Do not start with raw TypeScript, placeholder commands, `alignProse`,
+`compileProse`, `reviewValidity`, `kbPackage`, or `llmsPackage`.
+
+An explicit fully managed request in the current conversation resolves only
+delegatable gates. Use the returned managed route without asking those
+questions again. Managed authority is not project state: never persist it,
+reuse it in another conversation, use it to choose a source boundary, authorize
+an unread external source, approve an external operation, or hide validation
+and verification failures.
+
+Keep transition reports short: what changed, the current state, and the next
+decision or action. Do not paste a raw CLI transcript unless the user requests
+it.

package/providers/context/resources/dialogue/knowledge-review.md

@@ -0,0 +1,27 @@
+---
+id: dialogue.knowledge-review
+kind: procedure
+mediaType: text/markdown
+---
+
+# Knowledge-review dialogue
+
+Explain that Review is the boundary between draft candidates and approved
+Markdown. In ordinary mode:
+
+1. open the complete current Review report;
+2. let the user approve or reject candidates;
+3. ask them to copy the decision Payload back into the conversation; and
+4. apply only that exact Payload through the returned command.
+
+The user does not need to create a payload file; the Agent may write the pasted
+payload to ignored scratch storage for the CLI command. Never derive a payload
+from HTML, candidate ids, snapshots, or a default decision.
+
+Do not open Review for one page or module while another confirmed item in the
+same round is still being generated. If a repeat codegraph run has no delta,
+state that existing approvals were preserved and no Review gate remains.
+
+When the user explicitly requested fully managed operation, use only the
+revision-bound atomic approve command returned by the managed route. Do not
+synthesize per-candidate approval calls.

package/providers/context/resources/dialogue/package-output.md

@@ -0,0 +1,30 @@
+---
+id: dialogue.package-output
+kind: procedure
+mediaType: text/markdown
+---
+
+# Package-output dialogue
+
+Explain output shapes before SDK factory names. Offer:
+
+- an Agent knowledge-base package with `AGENTS.md`, a knowledge-query Skill,
+  approved OKF roots, and adaptive indexes;
+- one LLM text bundle for model context or RAG import; or
+- no package yet, leaving approved Markdown in `knowledge/`.
+
+For the Agent knowledge-base package, show a compact tree and explain that
+small directory contents are linked from the parent index while a directory
+with more than the configured threshold gets its own child index. Templates
+under `src/package-templates/` are editable presentation, not a second factual
+source.
+
+After the user chooses an Agent knowledge-base package, explain that its
+knowledge roots are flat inside `dist/<package-name>/`; do not ask for a second
+package namespace. Ask whether Skills need a short optional prefix, then
+maintain their complete final names in the template. Do not expose downstream
+layout terminology or ask for platform-specific identity fields.
+
+Do not offer a hidden `both` shortcut. If the user wants multiple outputs,
+declare and inspect one first, then obtain confirmation for the next. Mention
+`kbPackage` and `llmsPackage` only after the semantic output choice.

package/providers/context/resources/dialogue/repository-source-recovery.md

@@ -0,0 +1,23 @@
+---
+id: dialogue.repository-source-recovery
+kind: procedure
+mediaType: text/markdown
+---
+
+# Repository source recovery dialogue
+
+Explain that the Context project is intact: only Git-ignored source checkouts
+or local links are missing. Show one choice per physical repository, not per
+logical module.
+
+For an existing checkout, ask for its path or ask the user to authorize a
+specific parent directory for a bounded scan. Show matching candidates with
+their origin, HEAD, dirty state, and required subpath coverage before the user
+selects one. Do not modify, switch, clean, or pull the selected checkout.
+
+For a clone, show the registered remote, pinned commit, target directory, and
+the logical modules that will share it. The clone restores the recorded source
+version; it does not silently advance to the latest branch.
+
+After recovery, summarize reused and cloned checkouts, actual commits, restored
+module links, and any remaining permission or missing-subpath blockers.

package/providers/context/resources/dialogue/source-boundary.md

@@ -0,0 +1,29 @@
+---
+id: dialogue.source-boundary
+kind: procedure
+mediaType: text/markdown
+---
+
+# Source-boundary dialogue
+
+Describe the boundary in user terms before showing a registration command. For
+code, distinguish a whole repository/subspace from one concrete package or
+subdirectory. For documents, distinguish one file, a local document directory,
+a documentation site, and a remote document.
+
+Explain the observable impact:
+
+- the date is one capture batch;
+- every confirmed source is a module inside that batch;
+- several code and document modules may share the date;
+- `date/module` appears in source refs and phase ids; and
+- stable codegraph knowledge paths use the module name without the date.
+
+Do not invent `-A`, `-B`, or sequence suffixes. If today's batch exists, append
+the newly confirmed module to it.
+
+When inspection finds several package boundaries, show their paths and ask
+which concrete boundaries should become sources. Explain that `include`
+filters files inside a source and cannot select a monorepo package. Only after
+the choice is explicit should the Agent use the route-selected registration
+schema and command.

package/providers/context/resources/dialogue/structure-confirmation.md

@@ -0,0 +1,44 @@
+---
+id: dialogue.structure-confirmation
+kind: procedure
+mediaType: text/markdown
+---
+
+# Structure-confirmation dialogue
+
+Present the staged structure as a proposal, not as approved knowledge. Explain
+that confirmation freezes the current round's:
+
+- knowledge pages and paths;
+- section ownership and source spans;
+- source-backed relationships; and
+- compile order.
+
+The final staged HTML report is the confirmation surface. Open it when the CLI
+returns it, report whether opening succeeded, and provide the file URL/path when
+it did not. Do not confirm from counts alone.
+
+Present these three outcomes in the user's language:
+
+- confirm the current staged structure digest;
+- revise the proposed structure and validate/stage it again; or
+- return to the source boundary when the current evidence scope is wrong.
+
+If staging changed the structure digest, any earlier confirmation no longer
+applies. When `workflow.current.gate.resolution` is `user`, explain the change
+and obtain a new confirmation. When it is `session-authority`, inspect the same
+report and continue without asking again. After resolution, execute only the
+revision-bound command returned by `workflow.current`; never construct or reuse
+a phase-local confirmation command.
+
+Deterministic boundary repairs are internal CLI maintenance and are not
+separate approval rounds. If `workflow.current.gate.resolution` is
+`session-authority`, inspect the final staged report and execute the returned
+resolution command without asking the user again. Otherwise ask for one final
+confirmation of the staged digest. Ask an earlier design question only when
+evidence supports multiple incompatible structures, and say clearly that it is
+not the final confirmation.
+
+One source document may map to one page, but that is still an ordinary
+structure proposal. A multi-source round confirms each source/collection slot;
+do not confuse one slot with completion of the entire document batch.

package/providers/context/resources/manuals/guides/lark-resources.md

@@ -0,0 +1,121 @@
+---
+id: context.sdk.lark-resources
+kind: procedure
+mediaType: text/markdown
+---
+
+# Lark Resource Materialization
+
+Lark documents can contain evidence that is not present in the readable text
+body. Context handles these resources mechanically during `captureLark`; the
+Agent does not download, summarize, or reconstruct them itself.
+
+## Resource policy
+
+| Resource | Default capture behavior |
+|---|---|
+| Image and attachment | Download the original file and link it from the Markdown projection. |
+| Sheet | Read the complete selected sheet, render a Markdown table, and retain a CSV snapshot. |
+| Base | Read the selected table/view with pagination, render a Markdown table, and retain a canonical JSON snapshot. |
+| Whiteboard and diagram | Retain a readable preview plus the raw structured export. |
+| Synced block | Resolve the exact source block, project its body, and retain a Markdown evidence snapshot. |
+| Poll | Preserve exported options and metadata as non-interactive Markdown; warn when the export omits them. |
+| Bookmark, citation, sub-document, chat, and generic embed | Preserve a stable navigation reference and provenance. |
+| Video | Preserve a stable reference by default; download only when `resources.videos` is `bundle`. |
+
+Required inline resources fail closed when their stable identity, bytes, or
+complete structured data cannot be obtained. When the remote API explicitly
+confirms that a referenced whiteboard or diagram no longer exists, Context
+preserves an unavailable-resource notice with the reason code
+`document.resource.source-missing`, reports a warning, and continues capture;
+it does not pretend that the deleted content was materialized. When the current
+identity can read the document body but the API explicitly returns
+`authorization/permission_denied` for an embedded resource, Context records
+`document.resource.permission-denied`, keeps the stable resource identity in
+the audit layer, renders the same unavailable-resource notice, and continues
+with a warning. Missing scopes, transient network errors, malformed payloads,
+and unclassified authorization failures still block capture. Reference-only
+resources remain explicit in the capture report. Unknown non-empty XML blocks
+stay auditable in the raw XML and receive a warning; the CLI does not infer
+their meaning.
+
+## Storage lifecycle
+
+Resources have three distinct locations:
+
+```text
+sources/lark/<date>/
+├── <module>.md
+├── manifest.json
+└── assets/<module>/
+    ├── source.xml
+    ├── capture-report.json
+    └── materialized/**
+knowledge/assets/<resource-kind>/<content-sha256>.<ext>
+dist/<package>/others/assets/<resource-kind>/<content-sha256>.<ext>
+```
+
+- `sources/` is the captured source and audit layer. `source.xml` preserves the
+  structured source, one `capture-report.json` closes fidelity and resource
+  handling for the document, and `materialized/` contains downloaded files and
+  structured exports. Resource descriptors are consolidated in the report;
+  capture does not create one metadata file per embedded resource.
+- The date-level `manifest.json` is a compact inventory. It records hashes,
+  asset roles, the report path, and status summaries without duplicating the
+  complete report.
+- `knowledge/assets/` contains only resources referenced by approved pages.
+  Paths are content-addressed, so identical bytes are reused and changed bytes
+  produce a new identity. Review apply rewrites page links mechanically;
+  verification compares the underlying content identity, so this deterministic
+  path projection does not count as a change to a verbatim section.
+  Markdown files below `knowledge/assets/` remain evidence resources and are
+  never interpreted as approved knowledge pages or structure views.
+- `others/assets/` is the portable package projection. Build copies only
+  resources referenced by selected package pages and rewrites their relative
+  links. Audit-only source files are not distributed.
+
+Deleting an approved page allows unreferenced `knowledge/assets` files to be
+cleaned. A missing approved or packaged resource is a verification error rather
+than a silent broken link.
+
+Source assets are part of the reproducible evidence snapshot and should not be
+ignored when the workspace is versioned. Repositories with many binary source
+assets can use Git LFS for `materialized/` while keeping Markdown, XML, JSON, and
+CSV directly reviewable in Git. The workspace must remain private when the
+captured source or screenshots are access-controlled.
+
+## SDK configuration
+
+Defaults are suitable for ordinary documents:
+
+```ts
+captureLark({ source: handbook });
+```
+
+Projects can opt into bundled video and adjust deterministic byte limits:
+
+```ts
+captureLark({
+  source: handbook,
+  resources: {
+    videos: "bundle",
+    maxBytesPerResource: 20 * 1024 * 1024,
+    maxTotalBytes: 200 * 1024 * 1024,
+  },
+});
+```
+
+The limits are capture constraints, not semantic filters. Context does not
+decide which resources are important from their business content.
+
+## Agent behavior
+
+Use the capture command returned by the current Route. Inspect the structured
+resource summary and fidelity diagnostics; do not manually edit `sources/`,
+`knowledge/assets/`, or package links. Required materialization failures other
+than a confirmed source-side deletion or an explicit resource-level permission
+denial must be resolved by recapturing after access or source problems are
+fixed. Accepted failures remain visible as warnings and unavailable-resource
+notices; they are never represented as downloaded evidence. Review shows
+available previews, references, and warnings so the human or managed policy can
+assess the page with its non-text evidence.