@c4a/context 0.6.0-alpha.1

package/README.md

@@ -0,0 +1,100 @@
+# @c4a/context
+
+`@c4a/context` is the project-local SDK for Context workspaces.
+
+It provides the typed public surface used by `src/index.ts`: source references,
+phase declarations, review declarations, package declarations, and template
+metadata. `@c4a/context-cli` performs the filesystem side effects.
+
+## Install
+
+Published users install through the workspace created by `context init`.
+
+For local SDK development:
+
+```bash
+./start.sh link
+context init context --dev
+cd context
+bun install
+```
+
+## Tiny Example
+
+```ts
+import {
+  defineProject,
+  extractTs,
+  reviewValidity,
+  kbPackage,
+  source,
+} from "@c4a/context";
+
+const sampleLib = source("sample-lib");
+
+export default defineProject({
+  sources: [sampleLib],
+  phases: [
+    extractTs({ source: sampleLib, collection: "codegraph" }),
+    reviewValidity({ collection: "codegraph" }),
+  ],
+  packages: [
+    kbPackage({
+      name: "sample-lib-kb",
+      template: {
+        path: "src/package-templates/kb",
+        vars: { displayName: "Sample Library KB" },
+      },
+      select: { collections: ["codegraph"], okfRoots: ["wikis"] },
+    }),
+  ],
+});
+```
+
+## Read Next
+
+These files ship inside the installed package at `node_modules/@c4a/context/`:
+
+- [Docs index](./docs/README.md)
+- [Getting Started](./docs/getting-started.md)
+- [Agent Guide](./docs/guides/agent-guide.md)
+- [Package Outputs](./docs/guides/package-outputs.md)
+- [Project API](./docs/reference/project-api.md)
+- [Package Templates](./docs/reference/package-templates.md)
+
+Template examples ship in:
+
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
+
+Copy them into a workspace under `src/package-templates/` when declaring
+`kbPackage()` or `llmsPackage()`.
+
+Approved Markdown lives under internal `knowledge/<collection>/...` paths such
+as `knowledge/codegraph/...` or `knowledge/architecture/...`. During build, the
+CLI maps selected internal collections to OKF output roots such as `wikis/`,
+`guides/`, `rules/`, or `feats/`. OKF fields and Context extension fields live
+at the top level. Do not nest `sources`, `visibility`, or `code_symbols` under
+`context`, and do not add frontmatter `source_refs`. Section provenance lives in
+`context:section` source-ref comments.
+
+## Boundary
+
+The SDK stays declarative:
+
+- `defineProject`
+- `source`, `allSources`
+- `extractTs`, `reviewValidity`, `customPhase`
+- `kbPackage`, `llmsPackage`
+- source registry reading and validation helpers
+
+The CLI owns:
+
+- source materialization
+- extraction
+- review HTML and review apply
+- approved Markdown materialization
+- package build
+- verification
+- status and next-step guidance

package/contracts.d.ts

@@ -0,0 +1,31 @@
+export type DocumentMainlineCollection = "business" | "product" | "architecture" | "sop" | "faq" | "standards" | "decision" | "incident" | "test";
+export type CodegraphCollection = "codegraph";
+export type MainlineCollection = CodegraphCollection | DocumentMainlineCollection;
+export type TopLevelNamespace = MainlineCollection | "feats";
+export type OkfRoot = "guides" | "rules" | "wikis" | "feats";
+export type KnowledgeCollection = TopLevelNamespace;
+export type EntityStatus = "draft" | "approved" | "rejected" | "deprecated";
+export type PackageKind = "kb" | "llms";
+export type MarkdownTransform = (markdown: string) => string;
+export type FileCaptureProcessorDefinition = {
+    kind: "file.capture.processor.mdx-json-docs";
+    include?: readonly string[];
+    documentExtensions?: readonly string[];
+    routeMetadataFile?: string;
+};
+export type PackageSelectDefinition = {
+    collections?: readonly KnowledgeCollection[];
+    okfRoots?: readonly OkfRoot[];
+    include?: readonly string[];
+    exclude?: readonly string[];
+};
+export declare const DOC_MAINLINE_COLLECTIONS: readonly DocumentMainlineCollection[];
+export declare const MAINLINE_COLLECTIONS: readonly MainlineCollection[];
+export declare const TOP_LEVEL_NAMESPACES: readonly TopLevelNamespace[];
+export declare const OKF_ROOTS: readonly OkfRoot[];
+export declare const KNOWLEDGE_COLLECTIONS: readonly KnowledgeCollection[];
+export declare function assertKnowledgeCollection(value: string, field: string): asserts value is KnowledgeCollection;
+export declare function assertDocumentMainlineCollection(value: string, field: string): asserts value is DocumentMainlineCollection;
+export declare function assertMainlineCollection(value: string, field: string): asserts value is MainlineCollection;
+export declare function assertTopLevelNamespace(value: string, field: string): asserts value is TopLevelNamespace;
+export declare function assertOkfRoot(value: string, field: string): asserts value is OkfRoot;

package/docs/README.md

@@ -0,0 +1,39 @@
+# Context SDK Docs
+
+These docs ship inside the installed SDK package at:
+
+```text
+node_modules/@c4a/context/docs/
+```
+
+Agents should read these files before editing a Context workspace, especially
+before changing `src/index.ts` or package templates.
+
+## Read First
+
+- [Getting Started](./getting-started.md) — end-to-end component-library flow.
+- [Agent Guide](./guides/agent-guide.md) — what an agent should do, and what it should not inspect manually.
+- [Agent Dialogue](./guides/agent-dialogue.md) — how agents should explain human gates without exposing internal API details first.
+- [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
+- [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
+- [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.
+- [Template Variables](./reference/template-variables.md) — Handlebars variables, loops, comments, and default knowledge inventories.
+
+Approved Markdown and kb package OKF output follow the C4A OKF Profile:
+OKF fields and C4A extension fields live at the top level. Do not nest
+`sources`, `visibility`, or `code_symbols` under `context`, and do not add
+frontmatter `source_refs`. Section provenance lives in `context:section`
+source_ref span comments. The kb package root may contain agent files; the
+OKF-compatible surface is its selected `wikis/`, `guides/`, `rules/`, and
+`feats/` subtrees.
+
+## Installed Templates
+
+Template examples ship in:
+
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
+
+Copy or mirror these into a workspace under `src/package-templates/` when the
+project needs package outputs.

package/docs/getting-started.md

@@ -0,0 +1,320 @@
+# Getting Started
+
+This guide shows the common Context workspace shape. The same workspace can
+ingest source documents, code repositories, or both. Start with the user's
+source boundary, then declare the matching phases in `src/index.ts`.
+
+## 1. Initialize
+
+```bash
+context init context --dev
+cd context
+bun install
+context status
+```
+
+Use `--dev` only when testing a locally linked SDK. Published users can omit it.
+When operating through an Agent plugin, use the installed Context continuation entry from the project root after initialization; it reads `context status` and then calls the lower-level CLI primitives as needed. The exact slash command or skill name is host-specific.
+
+## 2. Choose And Register A Source Boundary
+
+First decide what one source should mean for this workspace. The source name is
+not only a label; it becomes a stable namespace in source refs, phase ids, and
+package naming. Approved knowledge paths are derived from collection,
+containment, and slug, not directly from the source name. ViewRef/NodeRef are
+identity fields, not path strings:
+
+```text
+knowledge/<collection>/<containment>/<slug>.md
+repo:<source-name>#symbol:...
+file:<source-name>/<document>#span:...
+lark:<source-name>/<document>#span:...
+dist/<source-name>-kb/...
+```
+
+For a Markdown or MDX document corpus, register a file source and keep the
+include list inside the user-approved boundary. Default file capture handles
+Markdown. For MDX documentation sites that use `_meta.json` route metadata,
+declare `captureFile({ source: docs, processor: mdxJsonDocs() })` in
+`src/index.ts`; `_meta.json` files are route metadata, not body evidence. The
+concrete command shape is available from
+`context source add file --help`; after registration, declare `captureFile`,
+`alignProse`, `compileProse`, and `reviewValidity`.
+
+For a Lark / Feishu document, register a Lark source with exactly one identity
+form, then declare `captureLark`, `alignProse`, `compileProse`, and
+`reviewValidity`.
+
+For a single component package, use the package directory as the repo source
+boundary:
+
+```bash
+context source add repo component-lib \
+  --local ../component-lib \
+  --remote <git-remote-url> \
+  --ref <commit-sha-or-prefix>
+context source ensure
+context source inspect component-lib
+```
+
+For a monorepo or subspace, choose the boundary deliberately:
+
+- If the user wants one package manual, point `--local` at that package
+  subdirectory and use a source name like `component-lib`.
+- If the user wants one unified manual for the whole subspace, point `--local`
+  at the subspace root and use a source name for that subspace.
+
+The long-term multi-module namespace shape is:
+
+```text
+knowledge/codegraph/product-ui/component-web/...
+knowledge/codegraph/product-ui/component-lynx/...
+```
+
+In the current repo extraction flow, a parent monorepo/subspace source is
+for inspection and planning first. Before real extraction, choose the concrete
+package/subdirectory boundary so the initial containment/slug plan stays
+focused and does not repeat package names accidentally.
+
+The CLI records the git root and subpath, then materializes
+`sources/repo/<name>` to the scoped view. Do not register the monorepo root and
+rely on `extractTs.include` to select a package; `include` is only a file filter
+inside the selected source boundary.
+
+If the user first registers a monorepo root, run `context source inspect <name>`
+before extraction. Show the listed module paths to the user as a tree and
+register the chosen package path as a separate source for current extraction. The
+inspect output includes package names, manifest paths, versions when available,
+and suggested `context source add` commands.
+
+Remote Git sources need the same boundary decision. Ask for the remote URL, the
+pinned commit/ref, and whether the user approves cloning. The CLI does not
+clone, checkout, reset, or fetch silently. If source material is missing or at
+the wrong ref, ask the user before running repo operations outside the CLI.
+
+## 3. Declare The Flow
+
+### Document Source Flow
+
+For source documents, keep the project declaration small and let the CLI guide
+the evidence views, structure confirmation, compile action schema, review, and
+close steps:
+
+```ts
+import {
+  alignProse,
+  captureFile,
+  compileProse,
+  defineProject,
+  reviewValidity,
+  source,
+} from "@c4a/context";
+
+const docs = source("product-docs");
+
+export default defineProject({
+  sources: [docs],
+  phases: [
+    captureFile({ source: docs }),
+    alignProse({ source: docs, collection: "architecture" }),
+    compileProse({ source: docs, collection: "architecture" }),
+    reviewValidity({ collection: "architecture" }),
+  ],
+  packages: [],
+});
+```
+
+Then start from `context status` or the installed Context continue Skill. The
+normal sequence is:
+
+1. capture the source into committed snapshots;
+2. investigate evidence and confirm `unapproved/structure.yaml`;
+3. compile source-bound draft pages from confirmed structure;
+4. review/apply approved pages;
+5. run close, verify, and build when packages are declared.
+
+Do not read `sources/` or raw Markdown directly after entering the Context
+workflow; use the evidence views and `source_ref` values returned by the CLI.
+
+### Code Source Flow
+
+Edit `src/index.ts`:
+
+```ts
+import { defineProject, extractTs, reviewValidity, source } from "@c4a/context";
+
+const componentLib = source("component-lib");
+
+export default defineProject({
+  sources: [componentLib],
+  phases: [
+    extractTs({ source: componentLib, collection: "codegraph" }),
+    reviewValidity({ collection: "codegraph" }),
+  ],
+  packages: [],
+});
+```
+
+Inspect and run:
+
+```bash
+context run --list
+context run extract:component-lib:codegraph --dry-run
+context run extract:component-lib:codegraph
+```
+
+When operating through an Agent, use `--dry-run --format json` as the CLI
+implementation for a no-write preview. For extract phases it returns a
+`preview` block with resolved sources, modules, file counts, symbol counts,
+candidate estimates, `knowledgeTree`, `knowledgePathExamples`, and module-level
+hints. Treat that preview as the scope check before producing draft candidates.
+
+The approved Markdown path is derived before review from collection,
+containment, and slug. NodeRef/ViewRef remain identity fields:
+
+```text
+knowledge/<collection>/<containment>/<slug>.md
+```
+
+Show the tree/path preview to the user before first extraction and describe it
+as a preview without writing candidates. If the source name, optional module
+segment, or path shape is not what the user expects, fix the source registration
+or source boundary before running extraction. A source that already points at
+one package/module root should not repeat the package name in the path.
+
+## 4. Review
+
+```bash
+context review html architecture --open
+```
+
+Use the generated HTML page to approve or reject candidates. If the browser does
+not open automatically, use the emitted `file://` URL. When
+finished, open `Payload` and copy the JSONL payload into the agent chat. The
+agent writes that pasted payload to a normal temporary file under the workspace
+`.tmp/` directory and runs:
+
+```bash
+context review apply <payload-file>
+```
+
+Do not hand-write approved Markdown. `context review apply` owns materialization
+from `unapproved/entities.jsonl` into `knowledge/`.
+Do not store review payloads through scratch files outside `.tmp/` or by
+editing workspace config.
+
+## 5. Build Packages
+
+This is a product decision point. Before editing `packages`, read
+[Package Outputs](./guides/package-outputs.md) and explain the output tree to the
+user.
+
+Recommended first output:
+
+```text
+dist/component-lib-kb/
+├── AGENTS.md
+├── skills/
+│   └── knowledge-query/
+│       └── SKILL.md
+└── wikis/
+    ├── index.md
+    ├── <group>/
+    │   ├── index.md
+    │   └── ...
+    └── ...
+```
+
+Choose an agent knowledge-base package when agents should consume the reviewed
+knowledge as a reusable package. After the user chooses this output shape,
+declare it with `kbPackage()`.
+
+The default `knowledge-query` skill teaches agents how to query copied OKF root
+directories structure-first, starting with `wikis/`, cite
+page/section evidence, inspect structure/build metadata when present, and report
+gaps instead of inventing unsupported answers. Before building, tell the user
+that `src/package-templates/kb/` is editable: they can change the default skill
+wording or add product-specific skills when the package needs behavior beyond
+knowledge lookup.
+
+Selected OKF root subtrees such as `wikis/`, `guides/`, `rules/`, and
+`feats/` follow the C4A OKF Profile. The package root contains agent files; the
+OKF-compatible interchange surface is the selected OKF root directories. Edit
+`src/package-templates/kb/wikis/index.md` before build to describe package
+scope, intended users, and query guidance; other selected OKF root indexes are
+generated unless the template supplies them.
+
+Alternative:
+
+```text
+dist/component-lib-llms/
+└── llms.txt
+```
+
+Choose an LLM text bundle when the user wants one text bundle for model/RAG
+import. After the user chooses this output shape, declare it with
+`llmsPackage()`.
+The user may also skip package output for now and keep only `knowledge/`.
+
+Do not offer `both` as a shortcut. If multiple outputs are needed, add one
+package first, inspect it, then add another after confirmation.
+
+Copy or create templates under `src/package-templates/`, inspect that they match
+the intended output shape, then declare packages. A `kbPackage()` template
+must contain at least one `SKILL.md`; the default template also includes
+`wikis/index.md`. The default template is a starting point, not proof that the
+final package is useful.
+
+```ts
+import {
+  defineProject,
+  extractTs,
+  reviewValidity,
+  kbPackage,
+  source,
+} from "@c4a/context";
+
+const componentLib = source("component-lib");
+
+export default defineProject({
+  sources: [componentLib],
+  phases: [
+    extractTs({ source: componentLib, collection: "codegraph" }),
+    reviewValidity({ collection: "codegraph" }),
+  ],
+  packages: [
+    kbPackage({
+      name: "component-lib-kb",
+      template: {
+        path: "src/package-templates/kb",
+        vars: { displayName: "Component Library KB" },
+      },
+      select: { include: ["codegraph/component-lib/**"] },
+    }),
+  ],
+});
+```
+
+If the user chooses an LLM text bundle instead, declare `llmsPackage()` in place
+of the agent knowledge-base package:
+
+```ts
+llmsPackage({
+  name: "component-lib-llms",
+  template: "src/package-templates/llms",
+  select: { include: ["codegraph/component-lib/**"] },
+});
+```
+
+Build and verify:
+
+```bash
+context build
+context verify
+context status
+```
+
+Outputs are written under `dist/<package-name>/`.
+
+After build, inspect `dist/<package-name>/` before calling the package usable.
+A clean command exit only means the workspace protocol is valid.