@c4a/context 0.6.0-beta.4 → 0.6.0-beta.6

package/README.md

@@ -30,7 +30,7 @@ import {
   source,
 } from "@c4a/context";
 
-const sampleLib = source("sample-lib");
+const sampleLib = source("20260712", "sample-lib");
 
 export default defineProject({
   sources: [sampleLib],

package/docs/getting-started.md

@@ -18,18 +18,17 @@ When operating through an Agent plugin, use the installed Context continuation e
 
 ## 2. Choose And Register A Source Boundary
 
-First decide what one source should mean for this workspace. By default, source
-registration omits a name and the CLI uses today's local date (`YYYYMMDD`) as
-the source namespace. Do not derive source names from filenames, directory
-names, or document content. If today's date already exists, pass an explicit
-date name. The source name 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:
+First decide what one source should mean for this workspace. Document sources
+use one date name (`YYYYMMDD`). Repo sources use two levels: the date is a
+capture batch and `--module` identifies the concrete package or code boundary.
+Several repo modules can therefore be registered under the same date. Use the
+confirmed package/module identity for `--module`; do not invent semantic source
+suffixes from prose or content. ViewRef/NodeRef are identity fields, not path
+strings:
 
 ```text
 knowledge/<collection>/<containment>/<slug>.md
-repo:<source-name>#symbol:...
+repo:<date>/<module>#symbol:...
 file:<source-name>/<document>#span:...
 lark:<source-name>/<document>#span:...
 dist/<source-name>-kb/...
@@ -54,46 +53,105 @@ For a Lark / Feishu document, register a Lark source with exactly one identity
 form, then declare `captureLark`, `alignProse`, `compileProse`, and
 `reviewValidity`.
 
+File and Lark sources use the same date-batch shape as repo sources. Multiple
+documents belong under one date instead of receiving `-2` / `-A` suffixes:
+
+```bash
+context source add lark 20260712 --module user-manual --url <wiki-url>
+context source add lark 20260712 --module migration-guide --url <wiki-url>
+context source add file 20260712 --module local-manual --local ../manual
+```
+
+When these sources are supplied together, they can be registered in one locked
+batch. Save the following as YAML/JSON or pipe it through stdin:
+
+```yaml
+sources:
+  - type: repo
+    module: component-lib
+    local: ../component-lib
+  - type: lark
+    url: <wiki-url>
+  - type: file
+    local: ../manual
+```
+
+```bash
+context source add batch 20260712 --input sources.yaml --format json
+```
+
+Do not run multiple `context source add` commands concurrently. All source
+registry writes use one project lock and atomic replacement; if the lock is
+held, wait for the active command and retry.
+
+The command returns each concrete derived document module; use that value in a
+declaration such as `source("20260712", "wiki-<digest>", { type: "lark" })`.
+Snapshots are written as sibling files under `sources/lark|file/20260712/` with
+one date-level `manifest.json`; phase ids and manifest entries use the logical
+`YYYYMMDD/module` identity without creating a module subdirectory.
+
+If several documents were requested together, register and declare every
+module first. An explicit request to capture/read those exact paths or URLs is
+the read confirmation for that requested batch; do not ask again after
+registration. Merely mentioning a possible source is not permission.
+`context status --format json` returns all remaining capture phases in
+`routing.command_plan`. Every item is marked `after-human-confirmation`, so one
+explicit confirmation can authorize the complete requested batch without
+pausing for another date name or collection choice between modules. If any
+module lacks a declaration, status returns `needs-capture-phase` and a precise
+`routing.configuration` action instead of an unexecutable command.
+
+When the workspace also contains repo sources, Context prioritizes untouched
+code after all document captures finish: status returns `ready-to-extract`
+until the code extraction round is current, then returns to document
+investigation. An existing document structure/compile gate is never interrupted.
+
 For a single component package, use the package directory as the repo source
 boundary:
 
 ```bash
-context source add repo \
+context source add repo 20260712 \
+  --module component-lib \
   --local ../component-lib \
   --remote <git-remote-url> \
   --ref <commit-sha-or-prefix>
-context source ensure
-context source inspect <source-name>
+context source ensure 20260712
+context source inspect 20260712/component-lib
 ```
 
+If `component-lib` and the Context workspace are inside the same Git checkout,
+the CLI stores the repo root relative to the workspace even when `--local` was
+absolute. The module symlink target is relative as well, so the checkout can be
+moved without rewriting source metadata. External checkouts may keep an
+absolute repo root.
+
+Repo batches must be valid calendar dates in `YYYYMMDD` form; suffixes such as
+`20260712-A` are rejected. `source ensure <date>` and `source inspect <date>`
+operate on every repo module registered under that date. A full
+`<date>/<module>` selector still targets one module.
+
 For a monorepo or subspace, choose the boundary deliberately:
 
-- If the user wants one package manual, point `--local` at that package
-  subdirectory and use the CLI-returned date source name in `src/index.ts`.
-- If the user wants one unified manual for the whole subspace, point `--local`
-  at the subspace root and use the CLI-returned date source name as that
-  namespace.
+- Register each confirmed package/subdirectory with its own `--module` under
+  the same date batch.
+- A parent monorepo registration is an inspection boundary only when it resolves
+  to multiple packages; extraction remains bound to concrete registered modules.
 
-The long-term multi-module namespace shape is:
+The long-term multi-module knowledge shape is stable across capture dates:
 
 ```text
-knowledge/codegraph/product-ui/component-web/...
-knowledge/codegraph/product-ui/component-lynx/...
+knowledge/codegraph/module-a/...
+knowledge/codegraph/module-b/...
 ```
 
-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 each module's git root and subpath, then materializes
+`sources/repo/<date>/<module>` to the scoped view. Do not rely on
+`extractTs.include` to select a package; `include` is only a file filter inside
+one selected module.
 
-The CLI records the git root and subpath, then materializes
-`sources/repo/<source-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 <source-name>`
+If the user first registers a monorepo root, run `context source inspect <date>/<module>`
 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
+register each chosen package path under the same date. The
 inspect output includes package names, manifest paths, versions when available,
 and suggested `context source add` commands.
 
@@ -120,7 +178,7 @@ import {
   source,
 } from "@c4a/context";
 
-const docs = source("20260704");
+const docs = source("20260704", "product-docs", { type: "file" });
 
 export default defineProject({
   sources: [docs],
@@ -139,9 +197,9 @@ 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.
+3. compile every source-bound View from confirmed structure;
+4. review/apply the complete candidate batch once;
+5. run close once, then 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.
@@ -153,7 +211,7 @@ Edit `src/index.ts`:
 ```ts
 import { defineProject, extractTs, reviewValidity, source } from "@c4a/context";
 
-const componentLib = source("20260704");
+const componentLib = source("20260712", "component-lib");
 
 export default defineProject({
   sources: [componentLib],
@@ -169,8 +227,8 @@ Inspect and run:
 
 ```bash
 context run --list
-context run extract:20260704:codegraph --dry-run
-context run extract:20260704:codegraph
+context run extract:20260712/component-lib:codegraph --dry-run
+context run extract:20260712/component-lib:codegraph
 ```
 
 When operating through an Agent, use `--dry-run --format json` as the CLI
@@ -179,18 +237,23 @@ implementation for a no-write preview. For extract phases it returns a
 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:
+The codegraph path keeps the stable module identity. The date stays in the repo
+source ref and phase id, not in the knowledge path:
 
 ```text
-knowledge/<collection>/<containment>/<slug>.md
+knowledge/codegraph/<module>/symbol/<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.
+as a preview without writing candidates. If the module or path shape is not
+what the user expects, fix the module registration before extraction. An
+extra repeated package segment below the module may indicate an over-broad
+boundary.
+
+When one confirmed round contains several repo modules, preview and run their
+extract phases sequentially but defer the human gate until every phase finishes.
+The final Codegraph Review contains the combined draft set; do not review one
+module at a time.
 
 ## 4. Review
 
@@ -200,7 +263,8 @@ 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
+finished, open `Payload` and copy the review decision Payload into the agent chat.
+Uniform decisions use one JSON line; exceptions add JSONL lines. The
 agent writes that pasted payload to a normal temporary file under the workspace
 `.tmp/` directory and runs:
 
@@ -284,7 +348,7 @@ import {
   source,
 } from "@c4a/context";
 
-const componentLib = source("20260704");
+const componentLib = source("20260712", "component-lib");
 
 export default defineProject({
   sources: [componentLib],
@@ -299,7 +363,7 @@ export default defineProject({
         path: "src/package-templates/kb",
         vars: { displayName: "Component Library KB" },
       },
-      select: { include: ["codegraph/20260704/**"] },
+      select: { include: ["codegraph/component-lib/**"] },
     }),
   ],
 });
@@ -312,7 +376,7 @@ of the agent knowledge-base package:
 llmsPackage({
   name: "component-lib-llms",
   template: "src/package-templates/llms",
-  select: { include: ["codegraph/20260704/**"] },
+  select: { include: ["codegraph/component-lib/**"] },
 });
 ```
 

package/docs/guides/agent-dialogue.md

@@ -54,7 +54,7 @@ Bad:
 
 ```text
 Please provide source name:
-context source add repo <name> --local <repo-or-subdir>
+context source add repo <date> --module <module> --local <repo-or-subdir>
 ```
 
 Good:
@@ -66,22 +66,17 @@ If you want one manual for only this package, choose the package directory as
 the source boundary. If you want one manual for the whole subspace, choose the
 subspace root.
 
-The CLI will use today's local date (`YYYYMMDD`) as the source name unless that
-date already exists. Do not invent a name from the folder, filenames, or content.
-The source name becomes part of source refs, phase ids, and package names.
-Approved knowledge paths are derived from collection, containment, and slug;
-NodeRef/ViewRef are identity fields, not path strings:
-knowledge/<collection>/<containment>/<slug>.md
-repo:<source-name>#...
-dist/<source-name>-kb/...
+The CLI uses today's local date (`YYYYMMDD`) as the repo batch. Each confirmed
+package is registered as a module under that date, so the same batch can contain
+web, Lynx, and shared modules without `-A/-B/-C` suffixes. The concrete selector
+`YYYYMMDD/module` becomes part of source refs and phase ids, while approved
+knowledge uses the stable module name without the date:
+knowledge/codegraph/<module>/...
+repo:YYYYMMDD/<module>#...
 
-If today's date already exists, ask the user for an explicit date name before
-registration. Do not add a sequence number automatically.
-
-For a multi-module subspace package shape, the date source name can group
-children like:
-knowledge/codegraph/product-ui/component-web/...
-knowledge/codegraph/product-ui/component-lynx/...
+If today's batch already exists, add the next confirmed code or document module
+to it; do not add a sequence number automatically. File/Lark registration
+returns a `YYYYMMDD/module` identity and never requires a second flat date name.
 
 For the current first extraction, I will still ask you to confirm the concrete
 package/subdirectory boundary before reading code.
@@ -104,8 +99,8 @@ Good:
 The source is registered, but registration did not read the document body.
 
 The next operation will read this local Markdown file or folder and write a
-committed snapshot under `sources/file/<source-name>/`. The source name is the
-date name returned by `context source add file --local <path>`. That snapshot is used
+committed sibling file under `sources/file/<date>/`, tracked by that date's single `manifest.json`. The concrete
+`YYYYMMDD/module` identity is returned by `context source add file`. That snapshot is used
 later for review, verify, and fresh-clone reproduction.
 
 Please confirm that I may read this document source now. After you confirm, I
@@ -119,8 +114,8 @@ For Lark / Feishu:
 The source is registered, but registration did not fetch the remote document.
 
 The next operation will read the Lark/Feishu document you provided and write a
-normalized snapshot under `sources/lark/<source-name>/`. The source name is the
-date name returned by `context source add lark ...`. The snapshot is
+normalized sibling file under `sources/lark/<date>/`, tracked by that date's single `manifest.json`. Several requested
+documents may share the date; each has its own module and snapshot. The snapshot is
 committed by default so verify can work offline and after a fresh clone. Access
 credentials stay in the Lark CLI; they are not written to this workspace. If
 your business repository wants to ignore this snapshot, that is a repository
@@ -180,6 +175,13 @@ a simple structure draft. It still goes through structure confirmation and
 source-bound compile; there is no separate shortcut that writes final page body
 directly from capture.
 
+Validator-required page splits and continuous-source Section splits are not a
+new approval round. Apply the returned repair route, validate until
+`confirmation_ready=true`, then stage and present the automatically opened HTML
+report for one final structure confirmation. If evidence leaves multiple
+incompatible semantic structures, ask only that design question and explicitly
+say it is not the final report-based review.
+
 ## Extraction Scope Gate
 
 Bad:
@@ -187,7 +189,7 @@ Bad:
 ```text
 是否按 Context 默认范围继续？
 extractTs({
-  source: source("20260704"),
+  source: source("20260712", "component-lib"),
   collection: "codegraph",
   // include defaults to ["src/**/*.{ts,tsx}"]
   // exportedOnly defaults to true
@@ -209,12 +211,19 @@ This means files outside `src/` and non-exported/internal helpers are skipped.
 If you want docs, tests, examples, or internal APIs included, say that before
 extraction.
 
+If the selected package has no standard package entry, do not ask the user to
+change its source or `package.json`. Explain two Context-owned choices: provide
+the source-relative API roots as configured entries, or scan every file matched
+by the confirmed file scope. Entry-based extraction preserves public API
+reachability; scan mode includes internal declarations by default.
+
 I will first generate a preview without writing candidates. The preview will
 show the file count, symbol count, candidate count, and planned `knowledge/`
 tree. I will only run extraction after that preview matches your expectation.
 ```
 
-Mention `extractTs`, `include`, `exportedOnly`, or `reviewValidity` only if the
+Mention `extractTs`, `include`, `entries`, `mode`, `exportedOnly`, or
+`reviewValidity` only if the
 user asks for implementation details, or when editing `src/index.ts` in a code
 summary.
 
@@ -241,6 +250,29 @@ You do not need to save a payload file; I will write a temporary file and run
 the apply command.
 ```
 
+For a multi-View document or multi-module code round, use this wording only
+after the CLI reports that the complete batch is prepared. Do not ask the user
+to review one page or module while other confirmed items in the same round are
+still being generated.
+
+For a repeated codegraph run with no Review delta, say instead:
+
+```text
+The source was checked and no added, changed, or removed code symbols need a
+decision. Existing approved symbols were preserved, so there is no human gate
+for this run and I can continue.
+```
+
+For an explicitly requested CI/CD path, say:
+
+```text
+I will run the codegraph phase with --auto-promote. It will apply only
+deterministic code add/update/remove deltas, refresh deterministic close when
+needed, run verification, and fail the pipeline if close or verification fails.
+Package build remains a separate publishing step. Semantic knowledge still
+requires Review.
+```
+
 ## Package Gate
 
 Bad: