@c4a/context 0.6.1-beta.1 → 0.6.1-beta.2

package/README.md

@@ -44,8 +44,9 @@ export default defineProject({
 
 `src/index.ts` is similar to a Webpack configuration for knowledge. It defines
 what enters the project, which transformations and gates run, and what is built
-at the end. The installed Agent plugin includes the skills and SDK manuals
-needed to maintain this configuration from a user's requirements.
+at the end. The installed Agent plugin provides thin entries; the current
+workflow route selects the procedures and manuals needed to maintain this
+configuration from a user's requirements.
 
 ## Public Surface
 
@@ -116,6 +117,12 @@ include `{{packageName}}`, `{{displayName}}`, `{{knowledgeCount}}`,
 `{{knowledgeGroups}}`, `{{knowledgeItems}}`, `{{knowledgeTree}}`, and
 `{{buildInventory}}`.
 
+Every KB package defaults `distribution.knowledgeNamespace` to its package
+`name`, producing a short single-level knowledge directory. Set the field
+explicitly when a multi-segment namespace such as
+`personal-user.123/package` is required. Context isolates OKF roots under the
+complete value; Skill names remain author-maintained and independent.
+
 For advanced routing and retrieval, a template may carry a local script such as
 `query.ts`, with a Skill describing when and how an Agent should call it. The
 Skill can also route the Agent to MCP servers, CLI commands, or other tools to

package/README.zh-CN.md

@@ -38,7 +38,7 @@ export default defineProject({
 });
 ```
 
-`src/index.ts` 有点像知识项目的 Webpack 配置：它定义哪些内容进入项目、经过哪些转换和门禁，以及最终构建什么产物。安装好的 Agent 插件带有编写技能和 SDK 说明文档，可以根据用户需求维护这份配置。
+`src/index.ts` 有点像知识项目的 Webpack 配置：它定义哪些内容进入项目、经过哪些转换和门禁，以及最终构建什么产物。安装好的 Agent 插件只提供薄入口，当前工作流路由会按需选择维护这份配置所需的流程资源和 SDK 文档。
 
 ## 主要 API
 
@@ -97,6 +97,10 @@ kb/
 
 模板使用 Handlebars 变量，可以作用于文件内容和路径。常用变量包括 `{{packageName}}`、`{{displayName}}`、`{{knowledgeCount}}`、`{{knowledgeGroups}}`、`{{knowledgeItems}}`、`{{knowledgeTree}}` 和 `{{buildInventory}}`。
 
+每个 KB 包默认使用包 `name` 作为 `distribution.knowledgeNamespace`，生成简短的
+单级知识目录。需要 `personal-user.123/package` 这类多段目录时可以显式配置该字段。
+Context 会按照完整 namespace 隔离各个 OKF 根目录；Skill 名称仍由作者独立维护。
+
 如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
 
 ## 状态边界

package/contracts.d.ts

@@ -19,6 +19,11 @@ export type PackageSelectDefinition = {
     include?: readonly string[];
     exclude?: readonly string[];
 };
+export type PackageNavigationDefinition = {
+    foldDirectoryIndexes: boolean;
+    maxInlineEntries: number;
+};
+export declare const DEFAULT_PACKAGE_NAVIGATION: Readonly<PackageNavigationDefinition>;
 export declare const DOC_MAINLINE_COLLECTIONS: readonly DocumentMainlineCollection[];
 export declare const MAINLINE_COLLECTIONS: readonly MainlineCollection[];
 export declare const TOP_LEVEL_NAMESPACES: readonly TopLevelNamespace[];

package/docs/README.md

@@ -6,14 +6,16 @@ These docs ship inside the installed SDK package at:
 node_modules/@c4a/context/docs/
 ```
 
-Agents should read these files before editing a Context workspace, especially
-before changing `src/index.ts` or package templates.
+For lifecycle work, Agents should first consume the resources selected by
+`context status --format json` `workflow.current`. Read these SDK manuals when
+the selected route requires project configuration, package templates, or
+general reference; do not preload the whole manual set.
 
 ## 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.
+- [Agent Dialogue](./guides/agent-dialogue.md) — stable dialogue principles and how route-selected gate resources are discovered.
 - [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.

package/docs/getting-started.md

@@ -10,14 +10,18 @@ source boundary, then declare the matching phases in `src/index.ts`.
 context init context --dev
 cd context
 bun install
-context status
+context status --format json
 ```
 
 Use `--dev` when testing a local link or prepared pack before the matching SDK
 version is published. It writes a `file:` dependency to the SDK resolved beside
 the active CLI. Published users can omit it and install the versioned SDK from
 the registry.
-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.
+When operating through an Agent plugin, use the installed Context continuation
+entry from the project root after initialization. It consumes
+`workflow.current`, loads only the selected resources, and calls lower-level
+CLI primitives as needed. The exact slash command or skill name is
+host-specific.
 
 ## 2. Choose And Register A Source Boundary
 
@@ -30,7 +34,8 @@ suffixes from prose or content. ViewRef/NodeRef are identity fields, not path
 strings:
 
 ```text
-knowledge/<collection>/<containment>/<slug>.md
+knowledge/<collection>/<slug>.md
+knowledge/<collection>/<containment>/<slug>.md  # intentional hierarchy only
 repo:<date>/<module>#symbol:...
 file:<source-name>/<document>#span:...
 lark:<source-name>/<document>#span:...
@@ -98,21 +103,27 @@ 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.
-
-After capture, status returns `captured-ready-to-classify` for document modules
-without an align declaration. Run the returned collection-neutral evidence
-views first; only then propose a mainline collection and ask for confirmation.
-The batch read permission does not itself choose a collection.
+`workflow.current.commands`. Every item requiring the confirmed read scope 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,
+`workflow.current.configuration` identifies the precise project change instead
+of returning an unexecutable command. Read every
+`workflow.current.resources.required` item before acting; long procedures and
+semantic rules remain available as files and are loaded only for the route that
+needs them.
+
+After capture, status selects `route.document.classification-required` for
+document modules without an align declaration. Run the Gate's returned
+collection-neutral inspection commands first; only then propose a mainline
+collection and ask for confirmation. Batch read permission does not choose a
+collection.
 
 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.
+code after all document captures finish: the current reason is
+`route.extract.pending-target` until the code extraction round is current,
+then routing 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:
@@ -173,8 +184,8 @@ the wrong ref, ask the user before running repo operations outside the CLI.
 ### 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:
+the evidence views, structure confirmation, deterministic compile projection,
+review, and close steps:
 
 ```ts
 import {
@@ -200,7 +211,8 @@ export default defineProject({
 });
 ```
 
-Then start from `context status` or the installed Context continue Skill. The
+Then start from `context status` or the installed host-specific Context
+continuation entry. The
 normal sequence is:
 
 1. capture the source into committed snapshots;
@@ -242,8 +254,11 @@ context run extract:20260712/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.
+resolved entry files, exported/internal counts, symbol-kind counts, candidate
+estimates, `knowledgeTree`, `knowledgePathExamples`, and module-level hints.
+Treat that preview as a structural scope check before producing draft
+candidates; the CLI does not decide which symbols are important to a business
+or audience.
 
 The codegraph path keeps the stable module identity. The date stays in the repo
 source ref and phase id, not in the knowledge path:
@@ -311,6 +326,15 @@ 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 package name becomes its stable single-level knowledge namespace by
+default. Ask for a custom namespace only when the user needs another value. An
+explicit namespace may contain several concise lowercase path segments, such
+as `group/package` or `personal-user.123/package`; each segment may use letters
+and numbers joined by hyphens or dots. Do not infer custom values from
+downstream platform identifiers. Ask separately whether the author wants a
+short Skill prefix, then maintain the complete final Skill directory name in
+the template.
+
 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

package/docs/guides/agent-dialogue.md

@@ -1,365 +1,53 @@
 # Agent Dialogue
 
-This guide defines how agents should talk to users while operating a Context
-workspace.
+Context human gates should be explained as product decisions, not exposed as
+SDK or CLI implementation details.
 
-## Principle
+## Current Authority
 
-Talk about the user decision first, then the implementation detail.
+Run:
 
-Do not start a human gate by exposing internal API names, default option names,
-or placeholder commands. The user needs to understand:
-
-- what decision is being made;
-- what will happen after they approve;
-- what files or knowledge shape will be affected;
-- what alternatives they can choose.
-
-CLI commands, source names, phase ids, status values, payload keys, and
-`source_ref` values are protocol text. Keep those exact when needed, but do not
-make them the main explanation.
-
-## Fully Managed Conversation
-
-If the user explicitly says the current conversation is fully managed, briefly
-confirm that eligible workflow decisions will proceed automatically, then use
-the CLI's `--managed` status loop. Do not ask the ordinary classification,
-extraction-scope, structure-confirmation, Review, or package-output questions.
-Continue to surface source/read permission, external operation requests, and
-validation or verification failures because managed mode does not authorize or
-hide them. The authorization ends with the conversation and must not be written
-to project configuration.
-
-## Human Gate Question Form
-
-When the decision has a small fixed option set, use the host's native
-multi-choice tool when available:
-
-- Claude Code: `AskUserQuestion`
-- Codex: use the available native user-input tool, for example
-  `request_user_input` when it is exposed
-- Cursor Plan Mode: `AskQuestion`
-
-If no native question tool is available, fall back to Markdown `A/B/C` choices.
-Each option must include a short impact statement. Do not ask an open-ended
-free-text question when the actual workflow has two or three known branches.
-The option labels must be semantic user choices, not API or factory names. Use
-implementation names such as `alignProse`, `compileProse`, `kbPackage`, or
-`llmsPackage` only in a technical follow-up, command, or `src/index.ts` change
-summary.
-
-Examples:
-
-- document structure gate: continue material investigation vs add user
-  structure guidance vs narrow the captured source;
-- package output: agent knowledge-base package vs LLM text bundle vs skip for
-  now;
-- stale approved page: create a replacement review candidate vs confirm the
-  existing content is still valid;
-- orphaned approved page: mark the page deprecated vs keep it as unverifiable
-  knowledge.
-
-## Source Boundary Gate
-
-Bad:
-
-```text
-Please provide source name:
-context source add repo <date> --module <module> --local <repo-or-subdir>
-```
-
-Good:
-
-```text
-Next we need to choose the knowledge source.
-
-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 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 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.
-```
-
-Only after that explanation should the agent show the concrete command it will
-run.
-
-## Document Read Permission Gate
-
-Bad:
-
-```text
-Running capture:file:docs now.
-```
-
-Good:
-
-```text
-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 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
-will declare the capture phase in `src/index.ts`, summarize that change, and
-run the capture command.
-```
-
-For Lark / Feishu:
-
-```text
-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 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
-policy decision and verify will report degraded offline evidence later.
-
-Please confirm that I may read this remote document now.
-```
-
-Do not run capture preview, capture, or refresh before this permission is clear.
-
-## Document Investigation Gate
-
-Bad:
-
-```text
-Run align:file:docs:architecture or compile:file:docs:architecture?
-```
-
-Good:
-
-```text
-The document source has been captured into a committed snapshot.
-
-Capture summary:
-- documents: <count>
-- title tree: <top-level titles or heading groups>
-- evidence views: read-plan, source-index --compact, span-detail, span-text
-
-Next I will investigate the material and propose a structure draft. That draft
-decides:
-
-- which knowledge pages should exist;
-- which sections belong to each page;
-- which relationships have source-backed evidence;
-- which questions remain unresolved.
-
-Confirming the structure will freeze paths, section ownership, relationships,
-and compile order for this round. No approved Markdown is written before review.
-
-You can choose:
-A. Continue material investigation and let me propose the structure draft.
-B. First give structure preferences, such as expected domains or naming.
-C. Go back and narrow or correct the captured source.
-```
-
-After the user chooses, update `src/index.ts` if the matching align/compile
-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 source `20260704`. No approved Markdown is written yet. The next gate
-is a structure draft for your confirmation.
-```
-
-If the user asks for one page per source document, explain that it is modeled as
-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:
-
-```text
-是否按 Context 默认范围继续？
-extractTs({
-  source: source("20260712", "component-lib"),
-  collection: "codegraph",
-  // include defaults to ["src/**/*.{ts,tsx}"]
-  // exportedOnly defaults to true
-})
-```
-
-Good:
-
-```text
-The source is ready and resolves to one package.
-
-Proposed extraction:
-- read TypeScript/TSX files under `src/`;
-- only include exported symbols such as components, functions, types, and props;
-- create draft candidates for human review;
-- no approved Markdown is written until you review the candidates.
-
-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`, `entries`, `mode`, `exportedOnly`, or
-`reviewValidity` only if the
-user asks for implementation details, or when editing `src/index.ts` in a code
-summary.
-
-## Review Gate
-
-Bad:
-
-```text
-Run reviewValidity and apply payload.
+```bash
+context status --format json
 ```
 
-Good:
+For a gate, `workflow.current.resources.required` includes the exact dialogue
+resource for that decision together with its operating procedure and current
+workspace view. Read those selected resources before asking the question. The
+gate-specific source-boundary, read-permission, classification, extraction,
+structure, Review, package, and evidence-maintenance guidance is intentionally
+not duplicated in this SDK manual.
 
-```text
-Draft candidates are ready. The next step is human review.
+This keeps a new Agent from loading every possible conversation script before
+it knows which decision is current.
 
-Open the review HTML, approve or reject candidates, then copy the Payload back
-into chat. I will only apply the payload you provide; I will not approve or
-reject candidates on your behalf. Review decides which draft entries become
-approved Markdown under `knowledge/`, and which entries stay rejected in the
-ledger.
+## Stable Principles
 
-You do not need to save a payload file; I will write a temporary file and run
-the apply command.
-```
+- Use the user's conversation language for explanations and questions.
+- Keep commands, paths, ids, payload fields, status values, and `source_ref`
+  tokens exact.
+- Explain what is being decided, what changes after confirmation, and which
+  alternatives exist before showing implementation detail.
+- Prefer the host's native choice UI for a small fixed option set. Otherwise
+  use concise A/B/C choices with one impact sentence each.
+- Use semantic labels such as “Agent knowledge-base package” rather than SDK
+  factory names such as `kbPackage`.
+- Do not infer a decision from a filename, URL, repository layout, example, or
+  previous conversation.
+- Keep transition reports short: what changed, the current state, and the next
+  decision or action.
 
-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.
+## Fully Managed Conversations
 
-For a repeated codegraph run with no Review delta, say instead:
+Only when the user explicitly requests fully managed operation in the current
+conversation, use:
 
-```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.
+```bash
+context status --managed --format json
 ```
 
-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:
-
-```text
-Choose one: skills, llms, both, none.
-```
-
-Good:
-
-```text
-Approved knowledge is ready. Now choose how it should be packaged.
-
-Recommended first output is an agent knowledge-base package:
-dist/<name>-kb/
-├── AGENTS.md
-├── skills/knowledge-query/SKILL.md
-└── wikis/
-    ├── index.md
-    ├── <group>/index.md
-    └── <group>/...
-
-This gives agents a reusable knowledge-query skill plus copied approved
-knowledge pages. The
-default query skill starts from OKF indexes, cites page/section evidence, uses
-structure/build metadata when present, and reports gaps rather than inventing
-unsupported answers. The template under `src/package-templates/kb/` is editable
-before build, including `wikis/index.md` for bundle scope and query guidance.
-The root index should stay shallow by default: it lists next-level directories,
-and `context build` generates child directory indexes so users can browse from
-bundle to group to page.
-```
-
-Offer the alternatives as user-facing choices:
-
-- Agent knowledge-base package: creates `dist/<name>-kb/` for agents to query
-  and cite approved knowledge pages.
-- LLM text bundle: creates `dist/<name>-llms/` for one text/RAG import bundle.
-- Skip for now: leaves approved Markdown in `knowledge/` without a `dist/`
-  package.
-
-Do not offer `both` as a shortcut. If the user wants multiple outputs, declare
-one package first, build and inspect it, then ask before adding another. Use
-`kbPackage` / `llmsPackage` only after the user has chosen the semantic output
-shape.
-
-## Evidence Maintenance Gates
-
-When approved knowledge still exists but the source evidence changed, explain
-that the approved page remains usable but is no longer fully current against
-the latest snapshot.
-
-Use semantic choices:
-
-- Create an updated draft for review: best when the source change may require
-  wording, scope, or facts to change. This creates a replacement candidate and
-  still requires review.
-- Confirm the current page is still valid: best when the source change is only
-  formatting, typo cleanup, or otherwise does not affect the approved content.
-  This re-binds the page to the current evidence without changing its body.
-
-When an approved page points to a source document that no longer exists in the
-current snapshot, do not offer replacement or re-binding. Use semantic choices:
-
-- Mark the page as deprecated: removes it from later package output while
-  preserving audit history.
-- Keep it as source-orphaned knowledge: leaves it approved, but verify/status
-  will keep reporting an evidence warning.
-
-## Reporting
-
-Keep reports short and state transitions oriented:
-
-- commands run;
-- current state;
-- what changed;
-- the next human decision, if any.
-
-Do not paste long raw CLI transcripts unless the user asks for exact output.
+The returned route decides which delegatable gates may proceed without another
+question. This authority is not project configuration and must not be persisted
+or reused in another conversation. It cannot choose source boundaries,
+authorize unread external sources or external operations, or bypass validation
+and verification.