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

package/plugins/skills/context-init/references/internal-procedures/skill-source-scope/references/capture-source.md

@@ -13,10 +13,10 @@ tools:
 Current capture discipline for document sources. The executable path is source
 registration plus the declared capture phase flow:
 
-- local Markdown/MDX file source: `context source add file <name> --local <path>`
-  followed by `context run capture:file:<name> --format json`;
-- Lark/Feishu source: `context source add lark <name> ...` followed by
-  `context run capture:lark:<name> --format json`;
+- local Markdown/MDX file source: `context source add file --local <path>`
+  followed by `context run capture:file:<source-name> --format json`;
+- Lark/Feishu source: `context source add lark ...` followed by
+  `context run capture:lark:<source-name> --format json`;
 - refresh: rerun the same declared capture phase after status or the user asks
   for recapture.
 
@@ -52,19 +52,29 @@ manager or version.
 Before choosing a local Markdown capture route, honor the surrounding task context. Driver documents such as run instructions, handbooks, READMEs, plans, feedback issues, corpus/index/manifests, and batch lists are not Context sources unless the user explicitly asks to ingest them. Capture only ingest targets that are already explicit in the user request; if they are missing, ask one clarification instead of capturing the driver document.
 
 - One or more local `.md` / `.mdx` files or a local documentation folder to ingest →
-  register one file source with the user-confirmed source name and boundary:
-  `context source add file <name> --local <file-or-folder>`. For an explicit
+  register one file source with the user-confirmed boundary:
+  `context source add file --local <file-or-folder>`. The CLI returns the date
+  source name (`YYYYMMDD`) to use in project phases. For an explicit
   batch inside a broader folder, preserve the user's include list on source
-  registration. Default file capture handles `.md`. For MDX documentation sites
-  that use `_meta.json`, declare `mdxJsonDocs()` on `captureFile` in
-  `src/index.ts`; keep `_meta.json` only when it is route metadata for the
-  selected document folder. It is captured as metadata, not body evidence.
-  Declare `captureFile({ source: source("<name>") })`, then run
-  `context run capture:file:<name> --format json`.
+  registration. Default file capture handles `.md`. If the CLI reports
+  document-site files such as `.mdx`, `_meta.json`, sidebars, or docs config,
+  stop and confirm whether the selected boundary is a documentation site before
+  changing capture configuration. For MDX documentation sites that use
+  `_meta.json`, declare `mdxJsonDocs()` on `captureFile` in `src/index.ts`;
+  keep `_meta.json` only when it is route metadata for the selected document
+  folder. The CLI captures it as metadata and generates
+  `__context_route_metadata.md` as mechanical route evidence; it also extracts
+  static MDX component props/children into `__context_mdx_component_text.md`
+  when components carry user-facing text. Declare
+  `captureFile({ source: source("<source-name>"), processor: mdxJsonDocs() })`, then
+  run `context run capture:file:<source-name> --format json`. If the selected MDX page
+  is empty or only mounts runtime-rendered content, tell the user that capture
+  found a document-site shell and ask for the rendered-site or data-source
+  boundary instead of inventing body text.
 - A Lark/Feishu URL, doc token, or wiki token → register one Lark source:
-  `context source add lark <name> --url <url>` or the matching token flag.
-  Declare `captureLark({ source: source("<name>") })`, then run
-  `context run capture:lark:<name> --format json`.
+  `context source add lark --url <url>` or the matching token flag.
+  Declare `captureLark({ source: source("<source-name>") })`, then run
+  `context run capture:lark:<source-name> --format json`.
 - Mixed local document and Lark document batches are separate sources unless
   the current CLI explicitly offers a combined source contract. Do not write an
   Agent-side URL/file loop.

package/plugins/skills/context-init/references/internal-procedures/skill-source-scope.md

@@ -21,22 +21,21 @@ Choose and validate what may become draft knowledge.
   file source, or Lark/Feishu document. Current CLI can execute repo sources,
   local file sources, and Lark document capture through the declared flow.
 - Treat source registration as a knowledge-boundary decision, not a parameter
-  prompt. Explain that the source name becomes a stable namespace in source
-  refs, phase ids, and package naming. Approved knowledge paths are derived
-  later from collection, containment, and slug. Give concrete examples before
-  asking for confirmation.
-- If the user already provided a path and only the source name is missing, still
-  explain what that name means. Do not ask "confirm source name" without saying
-  whether the boundary is a single package/module or a parent monorepo/subspace
-  namespace.
+  prompt. Do not invent semantic source names from paths, filenames, or source
+  body content. By default, omit the source name and let the CLI use today's
+  date (`YYYYMMDD`) as the source namespace. Explain that this namespace appears
+  in source refs, phase ids, and package naming; approved knowledge paths are
+  derived later from collection, containment, and slug.
+- If the default date source name already exists, stop and ask the user which
+  explicit date name to use. Do not auto-append sequence numbers and do not
+  summarize the source theme as a fallback.
 - Do not infer a source from cwd, parent directories, package names, monorepo
   layout, or git remote.
 - In monorepos, one source may conceptually be the whole repo/subspace or one
   package/subdirectory. If the user wants one package manual, prefer the
   package/subdirectory. If the user wants one unified knowledge product across
-  modules, explain that the source name becomes the repo/source identity and
-  may be used in codegraph NodeRefs such as `codegraph/product-ui/...` when the
-  extraction rules derive those refs. Current repo extraction
+  modules, explain that the date source namespace can be used in codegraph
+  NodeRefs when extraction rules derive grouped refs. Current repo extraction
   still requires choosing a concrete single-module extraction boundary before
   running extraction; do not run extraction against an ambiguous multi-module
   source.
@@ -74,11 +73,29 @@ Ask for a knowledge source in plain language and map it to the supported path:
 
 | User source | What to ask for | Current handling |
 |---|---|---|
-| Local code repo | knowledge boundary, stable source name, and local repo path | Register with `context source add repo <name> --local <path>`. CLI records git root + optional `subpath`; `sources/repo/<name>` becomes an ignored symlink to the chosen repo/subdir view. |
-| Local monorepo package/module | whether the source is the whole repo/subspace or one package/subdir; stable source name; chosen path | Register the chosen boundary as the repo source. If the user wants one package manual, register that package/subdir. If the user wants a unified subspace manual, register the subspace. Do not use `extractTs.include` as a package selector. |
-| Remote Git repo | knowledge boundary, stable source name, remote URL, pinned commit/ref, desired package/subdir, and permission to clone | CLI does not clone automatically. After explicit user approval, the agent may clone/checkout to an ignored local path, then register that local checkout. Cloned source content must not be committed. |
-| Local Markdown / document file or folder | document boundary, stable source name, local path, include glob if needed, and permission to read the source body | Register with `context source add file <name> --local <path>`, declare the matching capture phase, then hand off to material investigation and structure drafting after capture. Do not run capture before the user confirms read permission. |
-| Lark / Feishu document | document URL/token, intended collection, and permission to read remotely | Register with `context source add lark <name>` plus exactly one of `--url`, `--doc-token`, or `--wiki-token`; declare the matching capture phase, then hand off to material investigation and structure drafting after capture. Explain that capture writes a committed snapshot under `sources/lark/<name>/`, supports offline verify/fresh clone reproduction, and does not write credentials. Do not fetch through ad hoc scripts. |
+| Local code repo | knowledge boundary and local repo path | Register with `context source add repo --local <path>` unless the user explicitly provides a date source name. CLI records git root + optional `subpath`; `sources/repo/YYYYMMDD` becomes an ignored symlink to the chosen repo/subdir view. |
+| Local monorepo package/module | whether the source is the whole repo/subspace or one package/subdir; chosen path | Register the chosen boundary as the repo source. If the user wants one package manual, register that package/subdir. If the user wants a unified subspace manual, register the subspace. Do not use `extractTs.include` as a package selector. |
+| Remote Git repo | knowledge boundary, remote URL, pinned commit/ref, desired package/subdir, and permission to clone | CLI does not clone automatically. After explicit user approval, the agent may clone/checkout to an ignored local path, then register that local checkout. Cloned source content must not be committed. |
+| Local Markdown / document file or folder | document boundary, local path, include glob or include-list if needed, and permission to read the source body | Register with `context source add file --local <path>`, declare the matching capture phase, then hand off to material investigation and structure drafting after capture. Do not run capture before the user confirms read permission. |
+| Lark / Feishu document | document URL/token, intended collection, and permission to read remotely | Register with `context source add lark` plus exactly one of `--url`, `--doc-token`, or `--wiki-token`; declare the matching capture phase, then hand off to material investigation and structure drafting after capture. Explain that capture writes a committed snapshot under `sources/lark/YYYYMMDD/`, supports offline verify/fresh clone reproduction, and does not write credentials. Do not fetch through ad hoc scripts. |
+
+When asking for a document mainline collection, do not ask only "which
+collection?". Explain every available option in product language:
+
+| Collection | Use when the source is mainly about |
+|---|---|
+| `business` | 业务域、业务对象、行业/组织概念、非技术的领域知识 |
+| `product` | PRD、用户故事、产品行为、需求说明、验收口径 |
+| `architecture` | 系统架构、组件/模块设计、技术方案、工具链、平台能力 |
+| `sop` | SOP、操作流程、排障步骤、oncall/runbook、巡检维护 |
+| `faq` | 问答集合、常见问题、按问题检索的解释和处理建议 |
+| `standards` | 规范、标准、约束、检查清单、合规/质量规则 |
+| `decision` | 明确的方案选择、取舍理由、ADR、决策记录 |
+| `incident` | 事故复盘、故障时间线、影响面、根因、处置和预防措施 |
+| `test` | 测试计划、测试场景、验证矩阵、验收用例 |
+
+Do not offer `codegraph` or `feats` for prose document alignment. `codegraph`
+comes from code extraction, and `feats` is a later feature namespace.
 
 </reference>
 
@@ -92,48 +109,48 @@ choice:
 
 ```text
 You are choosing what one source means for this knowledge workspace.
-The source name becomes part of source refs and phase ids. Approved knowledge
+The date source name becomes part of source refs and phase ids. Approved knowledge
 paths are derived later from collection, containment, and slug. NodeRef and
 ViewRef are identity fields, not path strings.
 
 If the source is one package:
-knowledge/codegraph/component-lib/...
-repo:component-lib#symbol:...
-capture:file:component-lib
-dist/component-lib-kb/
+knowledge/codegraph/YYYYMMDD/...
+repo:YYYYMMDD#symbol:...
+capture:file:YYYYMMDD
+dist/YYYYMMDD-kb/
 
 If the source is one document source:
 knowledge/architecture/entity/example.md
-file:product-docs/getting-started.md#span:...
-align:file:product-docs:architecture
-dist/product-docs-kb/
+file:YYYYMMDD/getting-started.md#span:...
+align:file:YYYYMMDD:architecture
+dist/YYYYMMDD-kb/
 
 If the source is a parent monorepo/subspace namespace, later multi-module
 outputs can be shaped like:
-knowledge/codegraph/product-ui/component-web/...
-knowledge/codegraph/product-ui/component-lynx/...
+knowledge/codegraph/YYYYMMDD/component-web/...
+knowledge/codegraph/YYYYMMDD/component-lynx/...
 ```
 
-If the source already points at one package/module root, the path uses the
-source name once. An extra module/package segment is only expected when the
-chosen source boundary intentionally covers multiple modules. In the current workflow, treat that
-parent source as a planning/inspection boundary first; choose a concrete
-package/subdirectory source before real extraction.
+If the source already points at one package/module root, the source namespace
+is still the date name. An extra module/package segment is only expected when
+the chosen source boundary intentionally covers multiple modules. In the
+current workflow, treat that parent source as a planning/inspection boundary
+first; choose a concrete package/subdirectory source before real extraction.
 
 When the user has already provided a path, describe the current interpretation
-before asking for the name:
+and use the CLI date default:
 
 ```text
 I am treating this path as the source boundary:
 <path>
 
-If this path is one package/module, the source name will be used directly:
-source refs such as repo:<source-name>#...
+If this path is one package/module, the date source name will be used in
+source refs such as repo:YYYYMMDD#...
 
 If this path is a parent monorepo/subspace that contains multiple modules, the
-source name becomes the parent source namespace for grouped codegraph NodeRefs
+date source name becomes the parent source namespace for grouped codegraph NodeRefs
 when extraction derives those refs:
-knowledge/codegraph/<source-name>/<module-name>/...
+knowledge/codegraph/YYYYMMDD/<module-name>/...
 
 For the current extraction flow, a multi-module parent source is used for
 inspection/planning first. Before reading code, we still need a concrete
@@ -148,8 +165,9 @@ Then ask for one of:
 - Lark/Feishu document URL.
 
 Do not ask "what is the source name?" as the first or only question. Ask what
-they want the knowledge source to cover, then propose a source name derived from
-that boundary and explain the path impact.
+they want the knowledge source to cover, then use the date default. Ask for an
+explicit date name only when today's source name already exists or the user
+asks to override it.
 
 Good user-facing wording:
 
@@ -158,22 +176,22 @@ Next we need to add a knowledge source.
 
 If you only want a manual for the component package, choose that package
 directory as the source boundary, for example:
-name: component-lib
+name: YYYYMMDD
 path: /repo/packages/component-lib
 
 If you want one manual for the whole subspace, choose the subspace root:
-name: product-ui
+name: YYYYMMDD
 path: /repo/subspaces/product-ui
 
-The name is not just a label. It will appear in source refs such as
-repo:component-lib#... and in phase ids such as extract:component-lib:codegraph.
+The date name is not just a label. It will appear in source refs such as
+repo:YYYYMMDD#... and in phase ids such as extract:YYYYMMDD:codegraph.
 Approved paths are derived from collection, containment, and slug. NodeRef and
 ViewRef are identity fields, not path strings.
 
-For a unified subspace package shape, a parent source name such as `product-ui`
+For a unified subspace package shape, the date source name
 lets the output group child modules under that namespace:
-knowledge/codegraph/product-ui/component-web/...
-knowledge/codegraph/product-ui/component-lynx/...
+knowledge/codegraph/YYYYMMDD/component-web/...
+knowledge/codegraph/YYYYMMDD/component-lynx/...
 
 Current extraction can inspect a parent source, but it should extract from a
 confirmed single package/subdirectory source. If this path is a parent source,
@@ -186,14 +204,14 @@ a supported repo source.
 
 For a local repo source, ask for:
 
-- source boundary and stable source name;
+- source boundary;
 - local repo or package/subdirectory path;
 - remote/ref only when not inferable or when the user wants an explicit pin.
 
 After the user provides the choice, run:
 
 ```bash
-context source add repo <name> --local <repo-or-subdir>
+context source add repo --local <repo-or-subdir>
 context source ensure
 ```
 
@@ -207,30 +225,39 @@ cloned source content.
 For local Markdown/MDX document sources, after the user confirms the boundary, run:
 
 ```bash
-context source add file <name> --local <file-or-folder>
+context source add file --local <file-or-folder>
 ```
 
-Default file capture handles Markdown. For MDX documentation sites that use
-`_meta.json` route metadata, declare
-`captureFile({ source: source("<name>"), processor: mdxJsonDocs() })` in
-`src/index.ts`; included `_meta.json` files are route metadata, not body
-evidence. Use `--include` only when the approved boundary is narrower than the
-folder. Then explain that the next operation reads the approved document files
-and writes a committed snapshot under `sources/file/<name>/`. After the user
-confirms read permission, summarize the `src/index.ts` change or show an
-equivalent diff summary, and run the capture phase.
+Use an explicit `<name>` only when the user has approved a non-default date
+source name. Otherwise run `context source add file --local <file-or-folder>`.
+
+Default file capture handles Markdown. If `context source add file`,
+`context source inspect`, `context status`, or capture output reports that the
+source looks like an MDX documentation site, stop at the source boundary gate
+and ask the user to confirm that interpretation before changing `src/index.ts`.
+For MDX documentation sites that use `_meta.json` route metadata, declare
+`captureFile({ source: source("<date-name>"), processor: mdxJsonDocs() })` in
+`src/index.ts`; included `_meta.json` files are route metadata, and the CLI
+generates `__context_route_metadata.md` as mechanical route evidence. Use
+`--include` only when the approved boundary is narrower than the folder. For a
+long fixed batch, prefer `--include-list <file>` with one include per line;
+blank lines and `#` comments are ignored. Then explain that the next operation
+reads the approved document files and writes a committed snapshot under
+`sources/file/YYYYMMDD/`. After the user confirms read permission, summarize the
+`src/index.ts` change or show an equivalent diff summary, and run the capture
+phase.
 Apply [skill-source-scope/references/capture-source.md](skill-source-scope/references/capture-source.md) for route
 selection, dependency recovery, output handling, and final reporting, using the
 current capture phase command returned by `context status`.
 
 For Lark/Feishu document sources, register the source but do not fetch content
 with ad hoc scripts. Explain which remote document or wiki token will be read,
-that the snapshot is written under `sources/lark/<name>/`, that committed
+that the snapshot is written under `sources/lark/YYYYMMDD/`, that committed
 snapshots enable offline verify and fresh-clone reproduction, that whether to
 add extra ignore rules is a business repository decision, and that access
 credentials are not written to the workspace. Use the declared capture/align
 flow only after the user confirms remote reading. After declaring
-`captureLark({ source: source("<name>") })`, summarize the `src/index.ts`
+`captureLark({ source: source("<date-name>") })`, summarize the `src/index.ts`
 change or show an equivalent diff summary.
 Apply [skill-source-scope/references/capture-source.md](skill-source-scope/references/capture-source.md) for route
 selection, dependency recovery, output handling, and final reporting, using the
@@ -250,14 +277,14 @@ the choices without exposing internal API names first:
 - for the current executable flow, register one package/subdirectory as its
   own source when the user wants a focused package manual;
 - if the user is designing a unified subspace knowledge base, keep the
-  parent source name as the namespace decision, but do not run extraction until
-  the concrete module extraction boundary is confirmed.
+  date source namespace as the namespace decision, but do not run extraction
+  until the concrete module extraction boundary is confirmed.
 
 Wait for the user to choose. If the user chooses `packages/button`, register it
 as a separate source such as:
 
 ```bash
-context source add repo button --local <repo>/packages/button
+context source add repo --local <repo>/packages/button
 ```
 
 Do not model a monorepo package choice as `include: ["packages/button/src/**"]`
@@ -272,7 +299,7 @@ the capture summary first:
 - document count;
 - title tree, heading tree, or source span distribution from the CLI output;
 - available reading budget and evidence views;
-- snapshot path under `sources/file|lark/<source-name>/`;
+- snapshot path under `sources/file|lark/YYYYMMDD/`;
 - the fact that approved pages are planned through
   `unapproved/structure.yaml` before compile;
 - whether the source is local file/folder evidence or Lark/Feishu evidence.
@@ -334,11 +361,11 @@ I will first generate a preview without writing candidates. The preview will
 show counts plus the planned `knowledge/` tree.
 ```
 
-Only after the user confirms this product-level scope, declare the chosen source
-with `source("<name>")`, add the TypeScript extraction phase, and add the human
-review phase. Use `include` only for a file-level filter within the chosen
-source boundary. Mention the internal API names only in code-change summaries,
-or when the user asks for implementation details.
+Only after the user confirms this product-level scope, declare the chosen date
+source with `source("YYYYMMDD")`, add the TypeScript extraction phase, and add
+the human review phase. Use `include` only for a file-level filter within the
+chosen source boundary. Mention the internal API names only in code-change
+summaries, or when the user asks for implementation details.
 
 ### Step 5 — Show The Pre-extraction Preview
 
@@ -362,12 +389,12 @@ containment, and slug; NodeRef/ViewRef are identity fields, not path strings:
 knowledge/<collection>/<containment>/<slug>.md
 ```
 
-If source name, package name, module list, candidate estimate, or path shape is
-not what the user expects, stop and repair the source boundary or source name
+If date source name, package name, module list, candidate estimate, or path shape is
+not what the user expects, stop and repair the source boundary or explicit date name
 before extraction.
 
 For a single-module code source, a repeated path like
-`knowledge/codegraph/<source-name>/<package-name>/...` is usually a schema
+`knowledge/codegraph/<date-source-name>/<package-name>/...` is usually a schema
 problem or a wrong source boundary. Stop before extraction if the preview shows
 that shape unexpectedly.