@c4a/context 0.6.0-alpha.1 → 0.6.0-beta.1

package/docs/getting-started.md

@@ -18,9 +18,12 @@ 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. 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,
+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:
 
@@ -36,8 +39,14 @@ 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
+`src/index.ts`; `_meta.json` files are route metadata, and the CLI generates
+mechanical evidence pages for route facts and static MDX component text:
+`__context_route_metadata.md` and `__context_mdx_component_text.md`. If the CLI
+reports that a file source looks like a documentation site but lacks the
+processor, confirm the source boundary and add the processor before capture.
+If the selected page is only a runtime shell, capture the rendered-site source
+or project-specific data source explicitly; do not ask the agent to invent
+missing body text. The concrete command shape is available from
 `context source add file --help`; after registration, declare `captureFile`,
 `alignProse`, `compileProse`, and `reviewValidity`.
 
@@ -49,20 +58,21 @@ For a single component package, use the package directory as the repo source
 boundary:
 
 ```bash
-context source add repo component-lib \
+context source add repo \
   --local ../component-lib \
   --remote <git-remote-url> \
   --ref <commit-sha-or-prefix>
 context source ensure
-context source inspect component-lib
+context source inspect <source-name>
 ```
 
 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`.
+  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 a source name for that subspace.
+  at the subspace root and use the CLI-returned date source name as that
+  namespace.
 
 The long-term multi-module namespace shape is:
 
@@ -77,11 +87,11 @@ 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
+`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 <name>`
+If the user first registers a monorepo root, run `context source inspect <source-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,
@@ -110,7 +120,7 @@ import {
   source,
 } from "@c4a/context";
 
-const docs = source("product-docs");
+const docs = source("20260704");
 
 export default defineProject({
   sources: [docs],
@@ -143,7 +153,7 @@ Edit `src/index.ts`:
 ```ts
 import { defineProject, extractTs, reviewValidity, source } from "@c4a/context";
 
-const componentLib = source("component-lib");
+const componentLib = source("20260704");
 
 export default defineProject({
   sources: [componentLib],
@@ -159,8 +169,8 @@ Inspect and run:
 
 ```bash
 context run --list
-context run extract:component-lib:codegraph --dry-run
-context run extract:component-lib:codegraph
+context run extract:20260704:codegraph --dry-run
+context run extract:20260704:codegraph
 ```
 
 When operating through an Agent, use `--dry-run --format json` as the CLI
@@ -274,7 +284,7 @@ import {
   source,
 } from "@c4a/context";
 
-const componentLib = source("component-lib");
+const componentLib = source("20260704");
 
 export default defineProject({
   sources: [componentLib],
@@ -289,7 +299,7 @@ export default defineProject({
         path: "src/package-templates/kb",
         vars: { displayName: "Component Library KB" },
       },
-      select: { include: ["codegraph/component-lib/**"] },
+      select: { include: ["codegraph/20260704/**"] },
     }),
   ],
 });
@@ -302,7 +312,7 @@ of the agent knowledge-base package:
 llmsPackage({
   name: "component-lib-llms",
   template: "src/package-templates/llms",
-  select: { include: ["codegraph/component-lib/**"] },
+  select: { include: ["codegraph/20260704/**"] },
 });
 ```
 

package/docs/guides/agent-dialogue.md

@@ -66,6 +66,8 @@ 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:
@@ -73,18 +75,11 @@ knowledge/<collection>/<containment>/<slug>.md
 repo:<source-name>#...
 dist/<source-name>-kb/...
 
-If the user already gave a path and only the source name is missing, still
-explain what the name means:
+If today's date already exists, ask the user for an explicit date name before
+registration. Do not add a sequence number automatically.
 
-- if the path is one package/module, the name appears once in source refs and
-  phase ids;
-- if the path is a parent monorepo/subspace, the name is a parent namespace and
-  child modules can appear below it later;
-- current extraction should inspect a parent source first, then extract from
-  a confirmed package/subdirectory boundary.
-
-For a multi-module subspace package shape, a parent name such as product-ui
-can group children like:
+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/...
 
@@ -109,7 +104,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>/`. That snapshot is used
+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
 later for review, verify, and fresh-clone reproduction.
 
 Please confirm that I may read this document source now. After you confirm, I
@@ -123,7 +119,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 snapshot is
+normalized snapshot under `sources/lark/<source-name>/`. The source name is the
+date name returned by `context source add lark ...`. 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
@@ -174,7 +171,7 @@ phases are not declared yet, then summarize the change. For example:
 
 ```text
 I updated the project flow to add document structure planning and source-bound
-compile for `product-docs`. No approved Markdown is written yet. The next gate
+compile for source `20260704`. No approved Markdown is written yet. The next gate
 is a structure draft for your confirmation.
 ```
 
@@ -190,7 +187,7 @@ Bad:
 ```text
 是否按 Context 默认范围继续？
 extractTs({
-  source: source("component-lib"),
+  source: source("20260704"),
   collection: "codegraph",
   // include defaults to ["src/**/*.{ts,tsx}"]
   // exportedOnly defaults to true

package/docs/guides/agent-guide.md

@@ -46,7 +46,7 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 - `unapproved/entities.jsonl` is the committed draft/rejected/deprecated ledger.
 - `knowledge/` contains approved Markdown.
 - `dist/` contains generated package outputs.
-- file and Lark snapshots live under `sources/file/<name>/` and `sources/lark/<name>/`.
+- file and Lark snapshots live under `sources/file/<source-name>/` and `sources/lark/<source-name>/`.
 - `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks.
 
 Do not create hidden workspace state directories.
@@ -58,7 +58,7 @@ Present only the current workflow surface:
 | Task | Current route |
 |---|---|
 | Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
-| Capture document sources | Run the declared `capture:file:<source>` or `capture:lark:<source>` phase only after read permission. Capture writes committed snapshots under `sources/file/<name>/` or `sources/lark/<name>/`. |
+| Capture document sources | Run the declared `capture:file:<source>` or `capture:lark:<source>` phase only after read permission. Capture writes committed snapshots under `sources/file/<source-name>/` or `sources/lark/<source-name>/`. |
 | Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
 | Confirm prose structure | `alignProse` validates and stages `unapproved/structure.yaml`. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
 | Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |
@@ -80,9 +80,12 @@ user first.
 
 `missing-source` is a human gate. In user-facing language, describe the next
 action as adding a knowledge source, not as filling CLI placeholders. Treat this
-as a source boundary decision. Explain that the source name is a stable prefix
-that appears in source refs and phase ids. Approved paths are derived from
-collection, containment, and slug. NodeRef/ViewRef are identity fields, not path strings:
+as a source boundary decision. Explain that the CLI uses today's local date
+(`YYYYMMDD`) as the source name by default; do not invent a name from cwd,
+parent directories, monorepo layout, package names, git remotes, filenames, or
+document content. The source name appears in source refs and phase ids. Approved
+paths are derived from collection, containment, and slug. NodeRef/ViewRef are
+identity fields, not path strings:
 
 ```text
 knowledge/<collection>/<containment>/<slug>.md
@@ -102,26 +105,16 @@ source boundary intentionally covers multiple modules.
 Ask what the user wants the source to cover: a single local Markdown/MDX document,
 a local Markdown/MDX directory, an article/documentation repository as a file
 source, a Lark/Feishu document URL or token, a local code repo/package, a remote
-Git repo/package, or a multi-module namespace. Do not infer the source from cwd,
-parent directories, monorepo layout, package names, or git remotes. Do not ask
-for a raw source name as an isolated parameter; propose one only after the
-boundary is clear.
-
-If the user already provided a path and the remaining question is only the
-source name, still explain the boundary implication before asking for
-confirmation. A package/module path means the source name becomes the stable
-source-ref, phase-id, and package-output identity. A parent monorepo/subspace
-path means the source name is a source namespace for possible child modules,
-and current extraction must inspect that parent before choosing concrete
-package/subdirectory boundaries. Approved paths still come from collection,
-containment, and slug.
+Git repo/package, or a multi-module namespace. If today's date source name
+already exists, ask for an explicit date name; do not auto-append a sequence.
+Approved paths still come from collection, containment, and slug.
 
 Current execution supports repo sources, local Markdown/MDX file sources, and Lark /
 Feishu document sources. Local
-repo/package sources are registered with `context source add repo <name>
---local <path>`; the materialized `sources/repo/<name>` entry is an ignored
+repo/package sources are registered with `context source add repo --local <path>`;
+the materialized `sources/repo/<source-name>` entry is an ignored
 symlink to the selected checkout or subdirectory view. Local Markdown/MDX sources
-are registered with `context source add file <name> --local <path>` plus any
+are registered with `context source add file --local <path>` plus any
 needed `--include` patterns, captured with `captureFile`, then planned through
 `alignProse` and compiled with
 `compileProse`. A one-file-to-one-page outcome is a degenerate structure plan,
@@ -129,7 +122,7 @@ not a separate content path. Remote Git operations require explicit user approva
 clone/checkout; clone into an ignored local path, checkout the requested commit,
 then register that local checkout. Do not commit cloned source content. Lark /
 Feishu sources are registered as document sources, captured through the Lark
-capture phase, and written as committed snapshots under `sources/lark/<name>/`;
+capture phase, and written as committed snapshots under `sources/lark/<source-name>/`;
 do not fetch or import Lark content with ad hoc scripts.
 
 Extraction scope is also a human gate. If no extract phase is declared, explain
@@ -138,8 +131,8 @@ registered source and file/symbol range to ingest. Do not inspect the source
 repository to choose packages or globs on the user's behalf.
 
 For monorepos, one source may conceptually cover the whole repo/subspace or one
-package/subdirectory. Explain that the source name becomes a source-ref and
-phase-id namespace. A parent source name can support grouped codegraph NodeRefs
+package/subdirectory. Explain that the date source name becomes a source-ref and
+phase-id namespace. A parent date source name can support grouped codegraph NodeRefs
 such as `knowledge/codegraph/product-ui/component-web/...` and
 `knowledge/codegraph/product-ui/component-lynx/...`. In the current executable
 flow, use the whole repo/subspace only for inspection/planning. If the user wants

package/docs/reference/project-api.md

@@ -19,9 +19,13 @@ declaration list. Put heavy logic in imported transform files.
 
 ## Sources
 
-A source is a stable knowledge boundary, not only a display label. The source
+A source is a stable knowledge boundary, not only a display label. By default,
+`context source add repo/file/lark` uses today's local date (`YYYYMMDD`) as the
+source name. Do not derive the name from filenames, directory names, or document
+content. If today's date already exists, pass an explicit date name. The source
 name becomes a stable identity in source references, phase ids, and package
-naming. Approved knowledge paths are derived from collection, containment, and slug. NodeRef/ViewRef are identity fields, not path strings:
+naming. Approved knowledge paths are derived from collection, containment, and
+slug. NodeRef/ViewRef are identity fields, not path strings:
 
 ```text
 knowledge/<collection>/<containment>/<slug>.md
@@ -60,8 +64,7 @@ is a repo, file, or lark source:
 ```ts
 import { source } from "@c4a/context";
 
-const componentLib = source("component-lib");
-const docs = source("product-docs");
+const docs = source("20260704");
 ```
 
 ### `allSources("repo")`
@@ -100,8 +103,19 @@ captureFile({ source: docs, processor: mdxJsonDocs() });
 ```
 
 With that processor, `.md` and `.mdx` are document bodies. Included
-`_meta.json` files are captured as route metadata assets and surfaced in
-`read-plan` / `source-index`; they are not treated as body evidence.
+`_meta.json` files are captured as route metadata assets, surfaced in
+`read-plan` / `source-index`, and mechanically projected into
+`__context_route_metadata.md` so route facts can be cited as evidence. The route
+projection records the canonical extensionless route form instead of treating a
+local `.html` URL as the source of truth.
+
+MDX component text is extracted separately: string props such as `title`,
+`label`, `description`, `href`, `to`, and component children are projected into
+`__context_mdx_component_text.md` as generated evidence. The original `.mdx`
+file remains in the snapshot unchanged. If a documentation page renders body
+text only at runtime from application code or remote data, configure that
+documentation site as an explicit source boundary instead of hand-writing route
+or body facts.
 
 ```ts
 captureFile({ source: docs });
@@ -113,9 +127,11 @@ Phase id:
 capture:file:<source-name>
 ```
 
-Register the source first with `context source add file <name> --local <path>`.
+Register the source first with `context source add file --local <path>`.
 The first registration requires `--local`; the registry may later keep `local`
-only as a refresh hint while committed snapshots remain verifiable.
+only as a refresh hint while committed snapshots remain verifiable. If the
+default date source name already exists, pass an explicit date name:
+`context source add file 20260703 --local <path>`.
 
 ### `captureLark`
 
@@ -132,10 +148,10 @@ Phase id:
 capture:lark:<source-name>
 ```
 
-Register the source first with `context source add lark <name>` and exactly one
+Register the source first with `context source add lark` and exactly one
 identity flag: `--url`, `--doc-token`, or `--wiki-token`. Capture reads the
 remote document through the CLI runner, writes normalized snapshot files under
-`sources/lark/<name>/`, and does not write access credentials into the
+`sources/lark/<source-name>/`, and does not write access credentials into the
 workspace. Multi-document Lark organization goes through `alignProse`; the
 current workflow does not provide a one-step Lark stage shortcut.
 
@@ -247,8 +263,9 @@ Options:
 | `transform` | Optional markdown transform function or functions |
 
 In monorepos, make the package/subdirectory the source boundary. Register the
-chosen package path with `context source add repo <name> --local <package-dir>`
-and reference it with `source("<name>")`. Do not use `include` to choose a
+chosen package path with `context source add repo --local <package-dir>` and
+reference the CLI-returned date source name with `source("<source-name>")`.
+Do not use `include` to choose a
 package from a larger monorepo source.
 
 Use `context source inspect <source-name>` to list detected module/package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.0-beta.1",
   "type": "module",
   "dependencies": {
     "yaml": "^2.5.1",