@c4a/context 0.7.4 → 0.7.8

package/docs/guides/sessions.md

@@ -0,0 +1,50 @@
+# Prepare a conversation-summary source
+
+Use sessions for a bounded summary formed from an authorized conversation:
+requirements, design, troubleshooting, operational or general knowledge.
+Code association is optional. An Agent or external supplier prepares the summary
+before import. Do not scan host history, ingest the full transcript, invent a
+conversation from a diff, or move an unrelated conversation into note merely
+because it lacks a commit.
+
+Keep the problem, confirmed decisions, useful reasons, constraints and open
+questions. Remove repetitive turns, tool logs and abandoned attempts unless they
+explain a current limit. Preserve whether each statement was proposed, agreed,
+implemented or verified. If only a supplied summary is available, say so; do not
+claim to have read the original. Do not make up speakers, dates or approval.
+A session with no reusable information can remain outside the workspace.
+
+Save through `context source import --input <file> --format json`, using
+`type: sessions`, `name: YYYYMMDD/topic.md` and the prepared `markdown` string.
+Choose the actual conversation date, or collection date if unknown, and retain
+the same path for corrections. The summary needs no mandatory body headings.
+
+Optional `changes` associates one or several code changes. Each row accepts
+`commit` (full 40/64 hexadecimal Git SHA), `mr` (HTTP(S) MR/PR URL), and optional
+`repository`. At least commit or mr is needed per row; omit the entire field
+for unrelated sessions. Use actual known identifiers, never fabricated hashes.
+A reference does not prove merge, deployment, tests or authorize fetching code.
+The CLI stores this field in the source's YAML frontmatter, discovers it from
+that same file, and does not introduce a sidecar or separate registry.
+
+For example, an import may have `changes: [{mr: "https://git.example.org/team/project/merge_requests/42"}]`.
+This is an illustrative URL, not a lookup target. The same payload without
+changes imports an independent requirements discussion normally. Use the current
+base_digest to change text or associations; explicit `changes: []` clears the
+associations. Omission leaves the source's inline changes intact. When replacing
+only the summary body, preserve existing associations unless explicitly removed.
+Do not duplicate commit/MR fields into knowledge frontmatter.
+
+Saving alone does not start indexing. Select a compatible Sessions Provider for
+an independent reader topic, or keep an existing page's Code/Markdown primary
+and include the summary in its authorized evidence/read scope. If specialized
+interpretation is needed, explicitly select an extension from the Sessions or
+business Provider. Knowledge turns useful conclusions into answers, explanations
+and procedures, not a meeting recap. Existing structure.yaml source references
+connect each relevant page/section to the saved summary and its optional changes.
+
+Correct a faulty summary through source import with current base_digest and task
+adjustment for pinned inputs. If the summary is accurate but the page is wrong,
+revise the approved page. A new topic goes through structure review then normal
+Author/Review. Neither knowledge approval nor source storage approves an upstream
+change. A failed update retains source and approved knowledge for recovery.

package/docs/guides/workspace-commit.md

@@ -0,0 +1,45 @@
+# Commit workspace results
+
+Use Host Git tools, not an invented Context commit command. Commit only when
+the user requests it; fully managed production does not itself authorize Git
+commits or pushes. At the end of the entire requested production scope, after
+close and all requested builds with no pending tasks, a single optional commit
+suggestion is enough. Intermediate delivery is not that endpoint.
+
+## Select the files
+
+Locate the Context workspace and its actual Git root. Inspect status, staged
+changes, unstaged changes, untracked files and ignore rules. In an embedded
+workspace the Git root may be a much larger source repository. Explicitly select
+workspace files; never run blanket `git add -A` or commit the entire staged index.
+Check source records for required recovery information; a commit does not bundle
+ignored checkouts or runtime progress. Do not force-add ignored files or assume
+`dist` belongs in Git. Generated files are included only if the project's rules
+and selected scope require them.
+
+If there is no Git repository, establish the intended repository location before
+initializing one. If nothing changed, report that no commit is necessary. If the
+user asks for an intermediate snapshot, explain which saved files it contains
+and that it cannot resume ignored Author state from Git alone.
+
+## Commit the selected change
+
+Summarize the actual change and choose a message consistent with repository rules.
+Use precise paths and Git's scoped commit facilities or a carefully isolated
+index. `git commit --only -- <paths>` can exclude unrelated staged files; new files
+must first be known to the index. Inspect overlapping partially staged files
+before selecting this approach: do not silently include changes the user did
+not select. Preserve unrelated staged entries, including staged deletions.
+
+Git identity, hooks, signing, conflicts and permissions are environmental
+issues for the Agent to diagnose. Do not disable hooks or signing, rewrite global
+Git configuration, stash other work or bypass ignore rules to force success.
+Use an available authorized alternative or report the specific blocker.
+
+## Verify the result
+
+Read the actual commit SHA and its changed files/diff; compare against the
+selected scope. Verify unrelated worktree and index content remain unchanged.
+If a hook changed the result, inspect and report it before claiming completion.
+Report the SHA and a brief description. Do not push, publish or create a remote
+repository without the corresponding explicit request.

package/docs/guides/workspace-prepare.md

@@ -0,0 +1,72 @@
+# Prepare a workspace for the next task
+
+Use only for an explicit workspace preparation request. The goal is usable
+registered sources and no unfinished task, while retaining approved knowledge
+and configuration. Lead with Host tools and actual observations; do not start
+indexing merely because a status response offers production work.
+
+## Establish the scope
+
+Use `context entry` to locate the workspace. Inspect current work, active
+processes, Git changes and source registrations. Explain which unfinished
+drafts and queued maintenance will be discarded. Reuse the user's explicit
+authorization; ask only about an unresolved loss, version or access boundary.
+Wait for an active writer to finish and obtain its receipt before changing state.
+If status is broken, inspect its diagnostic and files with Host tools rather
+than treating failure as proof that the workspace is empty.
+
+## End the old task
+
+Run `context task prepare --format json`. It previews the exact Context-owned
+task files, including production, Review and maintenance state. It preserves
+approved pages, source records and snapshots, project configuration, repository
+checkouts, other `.tmp` files and existing outputs. It does not claim the output
+or sources are current.
+
+Once discarding the shown scope is authorized, execute the returned apply
+command with its plan digest. If the preview changes, inspect the new differences.
+On interruption, rerun the preview and use its resume command; never clear a
+transaction journal or repeat old Author submissions. Other incomplete writes
+must be recovered before cleanup. The completion clears task state only; check
+sources next. Do not manually delete the runtime directory to emulate this action.
+
+Other caches are optional cleanup, not a requirement to empty `.tmp`. Inspect
+their ownership and recoverability before deleting them with Host tools. Keep
+reports, unique material, unknown files and modified checkouts unless their
+specific loss is authorized. Do not delete locks, transaction records or active
+tool directories. Empty task directories can remain.
+
+## Restore usable sources
+
+For repositories, run `context source recovery-plan --format json` and read
+the installed repository recovery procedure and schema supplied by entry's
+workflow bundle: `repository-source-recovery.md` beside this guide and
+`../../schemas/repository-source-recovery.schema.json`. Reuse a matching local
+checkout or, when authorized, clone into a bounded location using
+`context source restore --input <workspace-input-file> --format json`.
+Group modules sharing a remote and fixed commit; do not clone per module.
+Check registered commit and module paths. Never reset a supplied dirty checkout.
+Authentication or checkout problems can be diagnosed with Host Git tools;
+refresh the recovery plan after fixing them. Do not substitute a newer commit.
+
+For Lark, inspect the stored body and required attachments against the source
+records. Use the Host's document tools and the [existing capture guide](knowledge-updates.md)
+to repair missing material, retaining the registered identity. A current remote
+response is not proof of an older snapshot: if it differs, explain that source
+updating is needed and resolve that choice before claiming recovery. If an old
+snapshot is unavailable, report the exact limitation. Do not automatically
+follow every document link or reread already complete materials.
+
+For note, sessions and local files, preserve formal source content and verify
+that declared paths can be read. Do not reconstruct lost original sources from
+generated knowledge or scan arbitrary local directories.
+
+## Finish
+
+Verify that no task files remain in the preparation preview, no writer remains,
+the required configuration can load, and selected sources resolve to their
+registered versions and paths. CLI inspection or direct Host checks are both
+valid; a failed check is not ready. Report outstanding blockers and their next
+action. Stop when ready for the next user request, without running Author or
+recapturing everything. Historical restoration may additionally require a
+close/build; see [restore a version](workspace-restore.md).

package/docs/guides/workspace-restore.md

@@ -0,0 +1,59 @@
+# Restore a historical workspace version
+
+Use the Agent's Git and environment tools. This restores selected workspace
+files and usable sources; it does not reset the entire repository, rewind source
+repositories, or restore ignored runtime progress.
+
+## Resolve the target
+
+Locate the workspace and Git root, then inspect history for that workspace path.
+With no explicit target, select the most recent commit saving its state to undo
+uncommitted results. “Previous version” instead selects the preceding relevant
+saved state, not mechanically `HEAD~1` of a large repository. Validate an explicit
+SHA. For dates, use the user's timezone and actual meaning (for example, as of
+end of that day), inspect candidate history and resolve ambiguity with the user.
+Git history can be nonlinear; do not choose an unrelated branch by timestamp.
+The final target is a concrete SHA and path scope, never a date string alone.
+
+Compare target files with current tracked, untracked and staged files. Include
+current additions absent at the target in the proposed removal scope. Keep
+unrelated files, existing staged work and ignored source checkouts. Account for
+workspace moves or renames instead of treating a missing old path as an empty
+version. Reuse explicit authorization; ask when the target or loss is unresolved.
+
+## Restore files and environment
+
+Wait for active Context writers and obtain their result. Use the task-state
+preview/apply from [workspace preparation](workspace-prepare.md) to abandon the
+authorized old work before restoring files; it also clears pending maintenance.
+Do not use an old Route after restoration.
+
+Use Git to restore only the agreed paths from the selected SHA. A scoped
+`git restore --source=<sha> --worktree -- <paths>` preserves branch history;
+decide separately how authorized overlapping staged changes should be handled.
+Use explicit deletion for agreed additions absent at the target. Never use a
+whole-repository `reset --hard` or `clean -fdx` as a workspace shortcut.
+
+Use the restored source records with the preparation guide to restore pinned
+repository versions, module paths, document snapshots and attachments. New remote
+content cannot stand in for lost old snapshots. Do not reclone usable sources.
+On interruption, inspect the actual file diff and remaining source gaps and
+continue those operations; do not assume the previous Git command completed or
+replay old task submissions.
+
+Old build output does not describe the restored version. If output is requested,
+follow the current close/build or approved-output rebuild capability from the
+[knowledge update guide](knowledge-updates.md); do not start full indexing merely
+because the restored source configuration is available. Until rebuilt, state
+that existing output is stale. If the historical schema is incompatible, diagnose
+the available migration or tool-version choice, report necessary adaptations,
+and do not pretend incompatible content is current or silently rewrite all pages.
+
+## Verify and stop
+
+Compare the selected files with the target commit, identify any agreed adaptations,
+verify unrelated changes/index entries survived, and check source readiness and
+absence of old task state. When building was requested, check the new output as
+well. If only some sources could be restored, report partial completion with the
+specific missing access or version. No automatic commit, branch rewrite or push;
+the user may separately [commit the restored results](workspace-commit.md).

package/docs/reference/code-extractors.md

@@ -20,20 +20,32 @@ declare a separate extraction phase in `src/index.ts`.
 | `@c4a/extract-ts` | TypeScript/JavaScript symbols, exports, imports, calls, and React Router routes |
 | `@c4a/extract-go` | Go declarations, imports, calls, and common HTTP routes |
 | `@c4a/extract-rush` | Rush projects, tags, entries, dependencies, and owner boundaries |
+| `@c4a/extract-thrift` | Thrift services, methods and declared data types |
+| `@c4a/extract-proto` | Protobuf messages, fields and service definitions |
+| `@c4a/extract-mdx` | Markdown/MDX document structure and source spans |
+| `@c4a/extract-contract` | Supported structured API contract declarations |
+| `@c4a/extract-style` | Stylesheet declarations, selectors and related structure |
+| `@c4a/extract-sql` | Supported SQL schema declarations |
 | `@c4a/extract` | Shared extraction result and adapter contracts |
 
 These packages do not create Candidate rows, write `knowledge/`, or control
-Review. The Code Indexer Provider owns those lifecycle responsibilities.
+Review. The CLI owns those lifecycle responsibilities; Providers interpret the
+supplied facts and sources and return structured semantic results. Package
+presence alone does not prove a parser is selected or supports every dialect.
+Use the selected profile's actual capabilities and parser diagnostics.
 
 ## Unsupported technologies
 
-When the current Provider cannot parse a required boundary, first use its
-supported customization ladder (`config`, instruction append, template
-override, then program extension). Add a reusable parser to the Provider only
-when the same technology boundary is useful across projects. Do not create a
-project-local parallel knowledge pipeline.
-
-Parser coverage is complete when every required inventory item has an explicit
-disposition and the resulting pages answer the declared reader questions. A
-large symbol count by itself is not useful coverage.
-
+When a required boundary is unsupported, distinguish a parser limitation from
+missing writing guidance. Config can select supported behavior; instructions or
+templates cannot create missing structural facts. Follow the current Route's
+capability-gap report and smallest supported customization step. A program
+extension requires its existing execution authorization. Prefer a reusable
+parser when the same technology is useful across projects; do not create a
+parallel project-local knowledge pipeline.
+
+Mechanical inventory closure requires an explicit disposition for each supplied
+item. It does not prove that the pages answer the reader's questions. Review
+checks usefulness and fidelity separately. Internal or out-of-scope items can
+have justified exclusions without generating pages; symbol count is not a
+knowledge-quality measure.

package/docs/reference/indexer-provider-protocol.md

@@ -1,12 +1,51 @@
 # Indexer Provider protocol
 
 Context defines one Provider manifest, `context-indexer.yaml`, with protocol
-`context.indexer.provider/v1`. Code and Markdown Providers use the same field
+`context.indexer.provider/v1`. Code, Markdown, Note and Sessions Providers use the same field
 tree; `domains`, profiles and declared operations describe their applicable
 inputs.
 
 This page documents the protocol surface currently exposed by `@c4a/context`.
-It does not imply that the 0.7.0 CLI Route or its release channel is complete.
+Use the current CLI Route for executable inputs, schemas and selected resources.
+A protocol validator exported by the SDK is not a separate production workflow.
+
+## Articles supported by approved knowledge
+
+An article plan may declare `knowledge_dependencies`: stable `artifact_ref`,
+optional `section_refs` (empty means the approved article), and `required`.
+Use references supplied by Context; reader titles and output paths are not
+article identities. Each article keeps its existing primary subject and owned
+members. Referencing another article does not assign its members again.
+
+The current Partition/Author workflow delivers ready upstream articles before
+dependent required articles. An unavailable dependency remains visible in the
+structure preview; `request-adjustment` returns to planning. It cannot finish
+as an empty Author wave. Optional Composer output does not satisfy a required
+article plan.
+
+Review saves the approved fact payloads, evidence coordinates and versions with
+the approved Markdown transaction. These remain in `knowledge/structure.yaml`
+after close and temporary-cache cleanup. Author receives authorized supporting
+facts separately from approved interpretation. Current source captures, the
+Provider's accepted evidence kinds and the approved article version constrain
+that projection. A stored snapshot alone never expands source access.
+
+Previously approved dependencies can reuse their registered source reader even
+when that source has no owned Partition group in the current wave. Only the
+referenced authorized files enter the supporting projection. Missing or changed
+source files remain an upstream update task.
+
+An approved dependency change produces a verification warning for downstream
+articles. Use the existing `context revise` action on an affected article; its
+current route exposes `knowledge_input` with supporting facts and interpretations.
+Review accepts the refreshed supporting version even when the Agent confirms
+that the wording can stay the same. A plain edit with unavailable support does
+not clear the warning. `--regenerate` remains the existing program-block rebuild
+option, not a prerequisite for revising a prose synthesis.
+
+Writing style, chapter drift and ordinary Provider version differences remain
+guidance. Changed source/approval identities invalidate an in-flight supporting
+projection; they are not semantic content judgments.
 
 ## Resources and execution
 
@@ -76,6 +115,15 @@ config against the Bundle's closed data-only schema, binds the project-local
 customization fingerprint and requires a policy digest for executable
 resources. Missing, duplicate, stale or extra inputs fail closed.
 
+Selection validation is not an upgrade gate on an instruction-only bundled
+Provider. On resume, the CLI resolves that Provider by Skill and portable
+distribution from the current installation, checks the required capabilities,
+and refreshes instruction delivery without comparing it to the registry's
+historical version/integrity. Compatible persisted tasks keep their original
+request/result identities. The current Route revision still prevents stale
+submissions. This does not change staged program execution authorization or
+allow results to be reused across changed source, config or result contracts.
+
 The final stable report excludes transport paths, delivery timestamps and
 runtime receipt digests. Those values remain in a separate runtime receipt
 projection, so rematerializing identical content does not make the selection
@@ -375,6 +423,19 @@ temporary Provider path.
 
 ## Controlled invocation
 
+Author result acceptance checks the actual task, source/module, subject and
+Provider layer. Provider integrity, bundle/config/customization fingerprints
+remain recorded metadata, not byte-equality gates between a resumed request and
+its result. Selected Facts are resolved by their supplied identity and source
+references; their current values are recorded without comparing a previous
+parser payload digest. Source-span line ranges may expand within the same file
+content. Structured declarations resolve actual file/item identities, not a
+previous inventory or signature fingerprint. Source file content checks,
+unknown-reference rejection and atomic write protection remain in force.
+
+These continuation rules do not relax executable program authorization or allow
+an Agent to select undeclared sources.
+
 `context.indexer.controlled-invocation/v1` binds:
 
 - the exact Indexer, Provider, version, Bundle integrity and stable Provider
@@ -387,7 +448,7 @@ temporary Provider path.
 - a stable trust-policy and authority digest;
 - timeout and stdin/stdout/stderr byte limits.
 
-The 0.7.0 built-in Host capability is `sandboxed_program: false`. A first-party,
+The built-in Host capability is `sandboxed_program: false`. A first-party,
 verified or exact project-authorized program may use the `trusted-program` path,
 which is not an isolation claim. An untrusted program without a real sandbox is
 not executable.
@@ -535,8 +596,11 @@ children, cycles, path collisions and unregistered files fail. Reader bodies
 over 1500 lines produce a non-blocking advisory only. Total physical Artifact
 count has no global maximum.
 
-An initial layout does not create a structural Gate. A content-only increment
-reuses the existing Artifact identity and also skips the Gate. Adding reader
+An initial layout does not create the protected `confirm-layout-change` Gate.
+The main lifecycle still reviews its semantic structure before Author in
+ordinary mode; new topics in an update receive that structure review too.
+A content-only increment reuses the existing Artifact identity and skips the
+protected layout-change Gate. Adding reader
 fan-out to an already approved Node, removing or renaming an Artifact,
 splitting/merging its declared lineage, moving a logical Section, or changing
 an approved collection/path is represented by a digest-bound layout change
@@ -585,9 +649,11 @@ ledger, answer workset, or special close route for them.
 Newly captured Markdown, tool snapshots, or other authorized material re-enter
 the normal `main-index` operation. The affected Partition and Author worksets
 run again, reconciliation is recomputed, and the user reviews the resulting
-knowledge Candidate once. Successful close writes only approved knowledge and
-the recovery metadata in `knowledge/structure.yaml`, then clears transient
-Indexer runtime state.
+knowledge Candidate through the existing content Review. Review apply writes
+approved Markdown; close projects `knowledge/structure.yaml` and verifies it.
+Delivery retains accepted work while more pages remain, then cleans completed
+transient state. Durable `processed_scopes` advance only after the selected
+scope's required work and build complete, not after one page in that scope.
 
 ## Detector and inspector
 
@@ -698,7 +764,7 @@ Only `{{variable:<id>}}` and `{{block:<id>}}` are accepted. Direct variables are
 semantic prose. A block source variable is a deterministic Fact projection,
 must bind canonical `fact_refs`, and must equal the CLI's normalized projection
 of those Facts. Blocks select one of
-the CLI-owned `bullet-list`, `key-value-table` or `json-code-block` renderers;
+the CLI-owned `bullet-list`, `key-value-table`, `json-code-block` or `public-contract-table` renderers;
 templates cannot register code or helpers. A block directive occupies its own
 template line so the renderer can retain an exact content-layer boundary. The
 contract and body must declare exactly the same Sections and placeholders.
@@ -713,12 +779,13 @@ or sufficient evidence is absent from the rendered Candidate. A required
 Section in the same state becomes the already-declared material-question
 transition and makes `review_ready` false.
 
-Before a Candidate can enter Review, Context rejects unknown directives,
-unresolved variables, template comments, example placeholders, standalone or
-bracketed `TODO`/`TBD`/`待补充`/`待生成` markers, title-only Sections and budget
-overflow. A source-backed sentence that discusses a known TODO is not treated
-as a placeholder merely because it contains that token; it remains semantic
-prose and therefore requires Agent Review. The rendered
+Context validates template-program directives, declared variable types and
+expansion limits before rendering. Supplied variable values and Section prose
+are content, not template programs: JSX, braces, comments, TODOs, headings and
+example placeholders do not cause a content-validation failure. Missing or
+invalid structured input is distinct from an author's choice of words.
+Unfilled authoring placeholders can be mentioned during the existing Agent or
+user Review, but are not an additional CLI gate. The rendered
 Section content, ordered content-layer ledger and evidence receive stable
 digests. Deterministic blocks contribute catalog completeness but never
 semantic-prose density. Later `build` projects this approved body; it does not
@@ -732,10 +799,37 @@ unit, one of its CLI-owned inventory members, or an authorized target-resolution
 identity. Missing owners, outside subjects, unknown evidence and evidence that
 is known globally but absent from the owner Section all fail Result validation.
 
-Main-run validation derives
-`context.indexer.generated-authoring-audit/v1`. It reports controlled generated
-placeholder and empty emitted-Section hard findings, proves that every emitted
-structured claim passed owner-local evidence coverage, and lists every
-semantic-prose block or direct authored template variable as
-`semantic-prose-agent-review-required`. It does not scan free prose to claim
-that unsupported natural-language assertions were mechanically detected.
+Main-run validation does not produce a prose-quality audit. Content usefulness,
+completeness and faithfulness belong to the existing Agent or user Review.
+Structured owner/source checks still run, but no keyword, punctuation, heading
+or sentence-pattern scan can reject an otherwise valid Result. Physical output
+checks distinguish a missing or blank body from an authored body; they do not
+decide whether headings, comments or short prose are sufficient knowledge.
+
+### Groups narrowed by a scope decision
+
+The CLI may attach `scope_change.removed_member_ids` to a derived PartitionPlan
+group after excluding only part of its membership. This is runtime provenance,
+not an extra field Provider authors should invent in semantic Partition results.
+The remaining identity stays stable; the old page form/template is no longer a
+binding choice. Author receives the change in `page_plan.scope_change` and must
+reassess the residual sources, title and reader task. It can choose an allowed
+page form or an applicable non-publishing outcome. This metadata does not belong
+in knowledge frontmatter and is not proof that remaining material is useful.
+
+## Incremental planning handoff
+
+A semantic Partition group may declare `ready_for_author: true` when the Agent
+has resolved its subject, primary ownership, reader task and shared dependencies.
+The CLI can then deliver an initial wave before all Partition tasks are accepted.
+This is an optional scheduling declaration, not a new evidence or approval gate.
+Absent/false groups wait; every inventory member still needs a final disposition.
+The original Partition ledger resumes after normal structure review, Author,
+Composer, content Review, close and successful build. Later material for the same
+subject reuses its page identity and approved prose. A wave finishing never means
+the remaining source scope is complete.
+
+Known code-symbol planning views provide member overviews with immutable full
+fact links and bounded captured-source access. Providers must inspect details
+when semantic boundaries are uncertain; unknown payload formats retain full
+reading. Author receives full selected facts and source material.

package/docs/reference/package-templates.md

@@ -182,7 +182,7 @@ Built-in variables:
 | `{{displayName}}` | Display name. Defaults to a title-cased `packageName`; override with `template.vars.displayName`. |
 | `{{knowledgeCount}}` | Number of selected approved Markdown files. |
 | `{{knowledgeTimestamp}}` | Latest `timestamp` from selected approved Markdown, or `1970-01-01T00:00:00.000Z` when empty. |
-| `{{knowledge}}` | Concatenated selected approved Markdown bundle. |
+| `{{knowledge}}` | Concatenated consumer projection of selected approved pages, with path headings and without lifecycle metadata. |
 | `{{approvedKnowledge}}` | Alias for `{{knowledge}}`. |
 | `{{knowledgeItems}}` | Array of selected approved knowledge page metadata for loops. |
 | `{{knowledgeGroups}}` | Selected approved knowledge pages grouped by OKF root and first directory segment; each item also exposes `internal_collection`. |
@@ -322,7 +322,7 @@ Approved Markdown under `knowledge/` and its deterministic
   revision, or build. Do not copy a compact page as a new page without using a
   Context authoring command;
 - do not nest Context production metadata under `context`; fields such as
-  `context.sources` and `context.code_symbols` are not part of the 0.6 profile;
+  `context.sources` and `context.code_symbols` are not accepted production fields;
 - section provenance lives in `<!-- context:section ... source_ref="..." -->`
   comments. When a Section needs more than one citation, the CLI preserves the
   complete set in its adjacent `context:source_refs` block;
@@ -352,8 +352,9 @@ treat the complete `source_ref` as opaque. Production pages do not expose
 Candidate fingerprints, Indexer digests, or `code_origin`.
 
 `#span:` refs retain source snapshot line ranges for human review, diffing, and
-stable re-pinning. They resolve against committed file/lark document snapshots,
-not the code symbol index.
+stable re-pinning. They resolve against the stored file/Lark snapshot or the saved
+Note/Sessions Markdown, not the code symbol index. A session's optional commit/MR
+association stays in its source file; knowledge does not duplicate those fields.
 
 The kb package root may contain agent files such as `AGENTS.md` and `skills/`.
 The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
@@ -373,11 +374,11 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 6. Writes output under `dist/<package-name>/`.
 
 `context-build-inventory.json` records what was selected and why. Each selected
-file includes `selected_by` entries such as `{ "kind": "collection" }` and a
-`production_metadata` object for selected page-level production fields. Child
-and relationship records use the inventory's canonical structure projection,
-`{ "kind": "okf_root" }`, `{ "kind": "include" }`, or
-`{ "kind": "default" }`. The inventory also exposes package-visible typed
+file includes `selected_by` entries such as `{ "kind": "collection" }`,
+`{ "kind": "okf_root" }`, `{ "kind": "include" }`, or `{ "kind": "default" }`,
+and a `production_metadata` object for selected page-level production fields.
+Child and relationship records use the inventory's canonical structure
+projection. The inventory exposes package-visible typed
 edges under `structure.edge_records`; these records are filtered to edges whose
 endpoints are present in the selected package. Use those edge records for
 relationship citations inside the package instead of assuming the workspace

package/docs/reference/project-api.md

@@ -26,14 +26,30 @@ state.
 
 ```ts
 const repo = source("20260901", "component-lib");
-const docs = source("product-docs", { type: "file" });
-const handbook = source("handbook", { type: "lark" });
-const everyRepo = allSources("repo");
+const docs = source("20260901/product-docs", { type: "file" });
+const handbook = source("20260901/handbook", { type: "lark" });
+const note = source("20260908/decision-context.md", { type: "note" });
+const session = source("20260908/design-discussion.md", { type: "sessions" });
+const everyRepo = allSources("repo"); // array: use ...everyRepo inside sources
+const everySession = allSources("sessions");
 ```
 
-References resolve against `sources/repo/index.yaml`,
-`sources/file/index.yaml`, and `sources/lark/index.yaml`. Register or refresh
-sources through `context source ...`; do not invent snapshot directories.
+Repo, file and Lark references resolve against their respective
+`sources/<type>/index.yaml`. Their names include the registration date and module.
+Register or refresh them through `context source ...`.
+
+Note and Sessions references resolve directly to saved Markdown under
+`sources/note/YYYYMMDD/topic.md` and `sources/sessions/YYYYMMDD/topic.md`.
+Use `context source import` to save them; they have no separate registry or
+capture phase. Explicitly include the desired typed references in `sources`,
+for example `sources: [note, session]`, or use `sources: [...everySession]`
+when all saved sessions are intended. Merely saving a source does not select it.
+
+A project's source list enables acquisition and initial selection; requirements
+and the selected Indexer's target/read scopes determine what it owns and may read.
+Supporting text does not require a separate page or primary Indexer. See
+[note preparation](../guides/note.md), [sessions preparation](../guides/sessions.md)
+and [knowledge updates](../guides/knowledge-updates.md).
 
 ## Capture phases
 
@@ -44,8 +60,10 @@ captureLark({ source: handbook });
 ```
 
 Capture only creates a deterministic readable snapshot. Classification,
-partitioning, authoring, Candidate creation, and Review belong to the selected
-Markdown Indexer.
+partitioning and authoring use the selected Provider's guidance. The CLI owns
+worksets, Candidate creation, Review application and delivery. Code, Markdown,
+Note and Sessions Providers can use authorized supporting documents without
+creating a second capture or knowledge pipeline.
 
 ## `customPhase`
 
@@ -79,8 +97,10 @@ may be rebuilt; it is not an authoring source.
 
 ## Indexer registry
 
-The Agent and CLI maintain `src/indexers.yaml` through typed proposals and
-Review gates. Each selected Indexer binds requirements and scopes to one
+When this file is absent, the configuration Route supplies the initial schema:
+write confirmed `requirements` with `indexers: []`, then re-evaluate. The Provider
+selection Action supplies its own completion schema; that payload is not the
+configuration file. Subsequent changes use typed proposals and applicable gates. Each selected Indexer binds requirements and scopes to one
 primary Provider, with optional declared layers or composers. Provider code
 must return the current Indexer result protocol; it must not write Candidate,
 knowledge, or Review files directly.
@@ -90,6 +110,20 @@ current workflow Route when it is needed.
 
 ## Persistent versus runtime state
 
-Commit source registries, `src/index.ts`, `src/indexers.yaml`, package templates,
-and approved knowledge. Do not commit `.tmp/context-runtime/`; it contains
-recoverable execution state and is cleaned after a successful close.
+Source registries and snapshots, saved notes/summaries, project declarations,
+package templates and approved knowledge are durable inputs. Version them only
+when Git operations are authorized. Keep `.tmp/context-runtime/` out of Git;
+it contains unfinished execution state, not the sole source of recovery truth.
+
+`knowledge/structure.yaml` keeps shared page/source metadata and compact
+`processed_scopes` for completed requirement/source/module ranges. A partial
+update or failed build does not advance the whole range's processed version.
+Session commit/MR associations stay in the saved source frontmatter, not copied
+into every knowledge page. Use the CLI to adjust or roll back current work;
+do not edit these baselines or remove runtime files to simulate completion.
+
+## Source visual conversion preference
+
+Workspace `package.json` accepts `context.convertVisuals` (boolean, default `true`). Initialization writes it explicitly; older workspaces without the field also default to enabled. This lets a capable Author Agent attempt faithful structural diagram/table conversion. Explicit session instructions override the saved preference. It does not disable native table capture or existing Mermaid when false.
+
+Diagram style follows the workspace’s editable `AGENTS.md`; newly initialized workspaces default to minimal theme-aware diagrams without decorative colors. If the Agent cannot read the image or cannot preserve its meaning, it retains the original through the existing asset workflow. Source-based reuse avoids rereading unchanged visuals; file integrity and package hashes continue to reflect actual output changes.