@c4a/context 0.7.8 → 0.7.10-alpha.1

package/docs/reference/package-templates.md

@@ -232,19 +232,15 @@ rejects it.
 The default kb template includes:
 
 - `skills/knowledge-query/SKILL.md`, a reusable skill that teaches agents to
-  query copied knowledge pages structure-first, cite page/section evidence, use
-  `context-build-inventory.json` edge records for package-visible
-  relationships, and report gaps instead of inventing unsupported answers. The
-  build inventory also exposes `structure.relationship_coverage` so a consumer
-  can distinguish an observed zero-edge result from unknown relationship
-  coverage. The
+  navigate copied knowledge pages, cite relevant text and its exported source
+  attribution, and report gaps instead of inventing unsupported answers. The
   default entry OKF root is `wikis/`; packages that select additional internal
   collections expose
   `guides/`, `rules/`, or `feats/` indexes when those roots are selected.
 - `skills/knowledge-query/scripts/search.mjs`, a dependency-free BM25 fallback
   for exact terms, mixed keyword queries, and large Markdown indexes. It chunks
   mechanically, returns inspectable paths and line ranges, and never replaces
-  source-backed relationship evidence.
+  reading the relevant source-backed explanation.
 - `wikis/index.md`, the editable OKF bundle entry page for the generated
   `dist/<package-name>/wikis/` directory.
 
@@ -261,10 +257,8 @@ The generated
 KB entry surface. Internal collections are mapped into OKF roots during build:
 `codeindex`, `business`, and `product` go to `wikis/`; `architecture`, `sop`,
 `faq`, `decision`, and `incident` go to `guides/`; `standards` and `test` go to
-`rules/`; and `feats` goes to `feats/`. Treat `wikis/` as the structured
-entity-and-relationship layer. Guides and rules may explain, operationalize,
-or constrain that knowledge, but directory placement alone does not establish
-a relationship.
+`rules/`; and `feats` goes to `feats/`. These roots organize articles by content
+type; directory placement does not establish a relationship or a subject graph.
 
 Default navigation rules:
 
@@ -307,54 +301,36 @@ wants project-specific behavior beyond knowledge lookup.
 
 ## Context OKF Profiles
 
-Approved Markdown under `knowledge/` and its deterministic
-`knowledge/structure.yaml` projection form the authoring source of truth:
-
-- top-level YAML frontmatter uses OKF fields such as `type`, `title`,
-  `description`, `tags`, `timestamp`, and `resource`;
-- each Markdown page keeps reader fields, stable page identity, `sources`, and a
-  small recovery capsule (`resource`, `node_type`, containment fields, and
-  relationship mode);
-- large or repeated machine state such as complete `code_symbols`, code
-  evidence, relationship records, candidate fingerprints, and optimization
-  decisions lives once in the corresponding `structure.yaml` view record;
-- Context readers hydrate that machine state in memory before verify, audit,
-  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 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;
-- do not add frontmatter `source_refs`; page-level provenance is derived from
-  section source refs when needed;
-- do not add `context` or `schema` fields.
-
-Package knowledge pages under `dist/<package-name>/` use a consumer projection.
-They retain reader-facing fields such as `title`, `type`, `description`, `tags`,
-`timestamp`, and custom non-lifecycle fields. Node identity, `resource`,
-`sources`, Section evidence comments, and build-only fields are omitted from the
-page. `context-build-inventory.json` records the distributed path, approved
-knowledge path, node identity, source summary, and package-visible structure.
-Maintainers return to the mapped `knowledge/` page for exact `sources` and
-`source_ref` attribution. `knowledge/` is never rewritten by this projection.
-
-Accepted section `source_ref` forms:
-
-```text
-src-N#symbol:<file>:<symbol-id>:<kind>@<digest>
-src-N#span:<heading-hint> L<start>-<end>@<span-hash>
-```
-
-The code symbol form includes the source-relative file so same-name symbols in
-different files resolve to one exact symbol-index row. Consumers should still
-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 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.
+Approved Markdown under `knowledge/` and the article index in
+`knowledge/structure.yaml` have separate responsibilities:
+
+- Markdown owns `title`, `type`, `description` and the ISO UTC `timestamp`.
+  `resource` and `tags` are optional reader metadata, not required identities.
+- Structure owns stable `article_id`, `path`, `collection`, `visibility`,
+  and fragment `sections` with their region `references`.
+- Markdown fragment markers contain only their stable ID:
+  `<!-- context:section id="usage" -->` and `<!-- /context:section -->`.
+  Structure records each corresponding ID and at most three source positions
+  per fragment, not three per article.
+- A reference contains `source_ref`, `locator: { path, start_line, end_line }`
+  and the Host-computed regional `content_digest`. Do not duplicate this in
+  Markdown frontmatter or comments.
+- Neither Markdown nor structure keeps a node graph, parser fact ledger,
+  evidence-binding table or a second copy of article prose.
+- Article moves retain identity through Context's existing revision workflow.
+  Direct Markdown copies alone do not include complete provenance.
+
+Package pages under `dist/<package-name>/` retain reader metadata and receive
+a generated Sources section derived from the article references and source
+registry. Repository links include file and line ranges; document links retain
+the captured document attribution. This export does not rewrite `knowledge/`.
+The build inventory maps exported pages back to their approved article paths.
+
+Source snapshots and regional baselines remain machine-managed. Update checks
+compare cited regions, relocating unchanged text only when its new position is
+unambiguous. Missing, changed or ambiguous regions require review; an unchanged
+region does not prove that uncited new material is irrelevant. A session's
+optional commit/MR association stays with its source document.
 
 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
@@ -377,12 +353,10 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 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
-`knowledge/structure.yaml` file is bundled.
+The `structure.articles` projection retains selected article identities and
+fragment source references. It does not contain graph nodes or typed edges.
+Published Markdown includes readable source attribution derived from these
+references; the Agent does not maintain a second source list in the page.
 
 For KB packages, the inventory records `package.distribution` as
 `layout: "flat"`, `knowledge_namespace: null`, and the four package-relative

package/docs/reference/project-api.md

@@ -65,6 +65,51 @@ 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.
 
+### Batch capture from the source registry
+
+When all registered Lark documents are intended for this project and share capture
+settings, read the registry once instead of copying its module names into
+`src/index.ts`. For the standard `src/index.ts` entry:
+
+```ts
+import { fileURLToPath } from "node:url";
+import {
+  allSources, captureLark, defineProject, loadSourcesRegistry, source,
+} from "@c4a/context";
+
+const workspaceRoot = fileURLToPath(new URL("../", import.meta.url));
+const registry = await loadSourcesRegistry({ rootDir: workspaceRoot });
+const documents = registry.larks.map(entry =>
+  source(entry.name, { type: "lark" }),
+);
+
+export default defineProject({
+  sources: [...allSources("repo"), ...documents],
+  phases: documents.map(document => captureLark({ source: document })),
+  packages: [],
+});
+```
+
+Merge this pattern into existing declarations; preserve unrelated phases and
+package outputs. Adjust the root calculation if the entry lives elsewhere.
+Registry loading only reads local registrations; it does not fetch documents.
+
+- `sources/lark/index.yaml` owns document identities, URLs and titles. The project
+  selects those identities and declares capture settings. This example includes
+  future registrations too; use it only when the entire registered set is intended.
+- For a subset, filter registry entries by the intended namespace or names before
+  mapping. Apply exceptional resource settings within the same map instead of
+  declaring a second phase for the same document.
+- File documents use `registry.files`, `source(entry.name, { type: "file" })`
+  and `captureFile`. Group by actual processor needs; do not apply `mdxJsonDocs()`
+  indiscriminately to all file sources.
+- `allSources("lark")` selects a collection; its array contains a collection
+  reference, not individual documents. It neither expands capture phases nor
+  supports mapping its entries into `captureLark`.
+- The map declares one phase per document. It does not fetch URLs, change capture
+  permissions, or request parallel execution. Run the declared phases through the
+  existing CLI flow so each document retains independent refresh and retry behavior.
+
 ## `customPhase`
 
 ```ts
@@ -83,6 +128,7 @@ kbPackage({
   name: "component-kb",
   template: "src/package-templates/kb",
   select: { collections: ["codeindex", "architecture"] },
+  site: { title: "Component knowledge", lang: "en-US", base: "/" },
 });
 
 llmsPackage({
@@ -95,6 +141,13 @@ llmsPackage({
 Package selection reads approved `knowledge/` only. `dist/` is generated and
 may be rebuilt; it is not an authoring source.
 
+`kbPackage.site` optionally adds a VitePress website at `dist/<base>-site/` in
+the same build, beside the KB directory. `<base>` removes one trailing `-kb`
+from the package name, if present. Omit it for KB-only output. It accepts `title`, `description`,
+`lang` and a deployment `base` path. Knowledge map is projected from
+`src/knowledge-map.yaml` independently of KB directories; see
+[Package Outputs](../guides/package-outputs.md#optional-static-documentation-website).
+
 ## Indexer registry
 
 When this file is absent, the configuration Route supplies the initial schema:

package/docs/reference/template-variables.md

@@ -135,13 +135,12 @@ Each item contains:
 | `sourcePath` | Approved knowledge path before OKF output mapping, for example `architecture/entity/button.md`. |
 | `approved_path` | Alias for `sourcePath`. |
 | `dist_path` | Alias for `path`. |
+| `article_id` | Stable article identity from the approved article index. |
 | `internalCollection` | Internal approved collection, for example `architecture`. |
 | `internal_collection` | Alias for `internalCollection`. |
 | `collection` | Internal approved collection; alias for `internalCollection`. |
 | `okf_root` | OKF output root, for example `wikis`, `guides`, `rules`, or `feats`. |
 | `okf_root_path` | Final flat package-relative OKF root. |
-| `node_ref` | Stable NodeRef from approved frontmatter, for example `entity/button`. |
-| `view_ref` | Stable ViewRef from approved frontmatter, for example `architecture:entity/button`. |
 | `pathWithinCollection` | Path below the OKF root, for example `architecture/entity/button.md`. |
 | `href` | Link relative to the template file currently being rendered. Use this in custom templates. |
 | `hrefFromTemplate` | Alias for `href`. |
@@ -151,7 +150,7 @@ Each item contains:
 | `type` | OKF `type` from frontmatter. |
 | `description` | OKF `description` from frontmatter, when present. |
 | `timestamp` | OKF `timestamp` from frontmatter, when present. |
-| `source` | First top-level `sources` entry without the `repo:` prefix, or the group name. |
+| `source` | First actual source reference from the article index, or the group name. |
 | `group` | First path segment under the OKF root. |
 | `parentPath` | Parent path below the OKF root. |
 | `depth` | Segment count below the OKF root. |

package/index.d.ts

@@ -1,3 +1,5 @@
+import { type PackageSiteDefinition } from "./packageSite.js";
+export { packageSiteSchema, type PackageSiteDefinition } from "./packageSite.js";
 import type { PackageNavigationDefinition, PackageSelectDefinition } from "./contracts.js";
 import type { PhaseDefinition, PhaseResourceReference } from "./phases.js";
 import type { ProjectSourceDefinition } from "./sources.js";
@@ -16,8 +18,8 @@ export type { ExpectedProviderResolution, IndexerCliReleaseManifest, IndexerHost
 export * from "./indexerProviderComposition.js";
 export * from "./indexerProviderSelectionProposal.js";
 export * from "./indexerCustomizationLadder.js";
-export { indexerMetricContractSchema, indexerArtifactPolicyVariantSchema, indexerInventoryDomainSchema, indexerOperatorContractDigest, indexerOperatorContractSchema, indexerProfileContractDigest, indexerProfileContractEntrySchema, indexerProfileContractSchema, indexerProfileSubjectKeySchema, indexerQuestionTargetDomainSchema, indexerReaderQuestionContractSchema, indexerSubjectKeyContractSchema, inflationSensitiveHardMaximum, validateIndexerOperatorContract, validateIndexerProfileContract, } from "./indexerProfileContract.js";
-export type { IndexerMetricContract, IndexerOperatorContract, IndexerProfileContract, IndexerProfileContractEntry, IndexerProfileSubjectKey, IndexerReaderQuestionContract, IndexerSubjectKeyContract, } from "./indexerProfileContract.js";
+export { indexerMetricContractSchema, indexerArtifactPolicyVariantSchema, indexerInventoryDomainSchema, indexerOperatorContractDigest, indexerOperatorContractSchema, indexerProfileContractDigest, indexerProfileContractEntrySchema, indexerProfileContractSchema, indexerQuestionTargetDomainSchema, indexerReaderQuestionContractSchema, inflationSensitiveHardMaximum, validateIndexerOperatorContract, validateIndexerProfileContract, } from "./indexerProfileContract.js";
+export type { IndexerMetricContract, IndexerOperatorContract, IndexerProfileContract, IndexerProfileContractEntry, IndexerReaderQuestionContract, } from "./indexerProfileContract.js";
 export { createIndexerOverlayValidationReceipt, indexerContractOverlayDigest, indexerContractOverlaySchema, indexerOverlayValidationReceiptDigest, indexerOverlayValidationReceiptSchema, validateIndexerContractOverlay, validateIndexerOverlayValidationReceipt, } from "./indexerContractOverlay.js";
 export type { IndexerContractOverlay, IndexerOverlayConformanceReport, IndexerOverlayValidationReceipt, } from "./indexerContractOverlay.js";
 export * from "./indexerOverlayQuestionAmendment.js";
@@ -28,23 +30,19 @@ export type { IndexerEvidenceRef, IndexerLayerCompositionInput, IndexerLayerFrag
 export * from "./indexerArtifact.js";
 export { canonicalIndexerNodeRef, indexerSubjectKeySchema, } from "./indexerSubjectIdentity.js";
 export type { IndexerSubjectKey } from "./indexerSubjectIdentity.js";
-export * from "./indexerSubjectKeyAuthority.js";
 export { buildIndexerPostAuthorFragmentRequest, composeIndexerPostAuthorEnvelope, indexerComposedResultEnvelopeSchema, indexerComposerInvocationReceiptSchema, indexerEffectiveComposerSchema, indexerEffectiveComposerSetSchema, indexerLayerFragmentRunResultSchema, indexerPostAuthorFragmentRequestSchema, indexerPostAuthorWorksetDigest, indexerPostAuthorWorksetSchema, indexerPostAuthorWorksetSetDigest, indexerPostAuthorWorksetSetSchema, indexerPrimaryResultViewDigest, indexerPrimaryResultViewSchema, materializeIndexerEffectiveArtifactSet, materializeIndexerPrimaryResultView, materializeIndexerPrimaryResultViewFromArtifactResult, planIndexerPostAuthorComposition, resolveEffectiveIndexerComposers, validateIndexerPostAuthorFragmentResult, validateIndexerPostAuthorFragmentRequest, validateIndexerEffectiveComposerSet, validateIndexerPrimaryResultView, } from "./indexerPostAuthorComposition.js";
-export type { IndexerComposedResultEnvelope, IndexerComposerInvocationReceipt, IndexerEffectiveComposer, IndexerEffectiveComposerSet, IndexerEffectiveArtifactSet, IndexerLayerFragmentRunResult, IndexerPostAuthorFragmentRequest, IndexerPostAuthorPlan, IndexerPostAuthorWorkset, IndexerPostAuthorWorksetSet, IndexerPrimaryArtifactView, IndexerPrimaryFactView, IndexerPrimaryResultView, } from "./indexerPostAuthorComposition.js";
-export { buildIndexerMainWorkset, buildIndexerMainWorksetSet, buildIndexerRepairIntent, buildIndexerMainTransportBatch, buildIndexerTargetResolutionView, indexerMainWorksetDigest, indexerMainWorksetSchema, indexerMainWorksetSetDigest, indexerMainWorksetSetSchema, indexerMainTransportBatchSchema, indexerOwnerCohortRef, indexerTargetResolutionViewDigest, indexerTargetResolutionViewSchema, validateIndexerMainWorkset, validateIndexerMainWorksetSet, validateIndexerRepairIntent, validateIndexerTargetResolutionView, } from "./indexerMainWorkset.js";
-export type { IndexerMainAuthorWorkset, IndexerMainPartitionWorkset, IndexerMainWorkset, IndexerMainWorksetSet, IndexerRepairIntent, IndexerMainTransportBatch, IndexerTargetResolutionView, } from "./indexerMainWorkset.js";
+export type { IndexerComposedResultEnvelope, IndexerComposerInvocationReceipt, IndexerEffectiveComposer, IndexerEffectiveComposerSet, IndexerEffectiveArtifactSet, IndexerLayerFragmentRunResult, IndexerPostAuthorFragmentRequest, IndexerPostAuthorPlan, IndexerPostAuthorWorkset, IndexerPostAuthorWorksetSet, IndexerPrimaryArtifactView, IndexerPrimaryResultView, } from "./indexerPostAuthorComposition.js";
+export { buildIndexerMainWorkset, buildIndexerMainWorksetSet, buildIndexerRepairIntent, buildIndexerMainTransportBatch, indexerMainWorksetDigest, indexerMainWorksetSchema, indexerMainWorksetSetDigest, indexerMainWorksetSetSchema, indexerMainTransportBatchSchema, indexerOwnerCohortRef, validateIndexerMainWorkset, validateIndexerMainWorksetSet, validateIndexerRepairIntent, } from "./indexerMainWorkset.js";
+export type { IndexerMainAuthorWorkset, IndexerMainPartitionWorkset, IndexerMainWorkset, IndexerMainWorksetSet, IndexerRepairIntent, IndexerMainTransportBatch, } from "./indexerMainWorkset.js";
 export { indexerPartitionGroupBindingDigest, indexerPartitionGroupProjectionDigest, indexerPartitionPlanBindingDigest, indexerPartitionPlanCanonicalHash, indexerPartitionPlanSchema, indexerPartitionStrategySchema, indexerPartitionStrategySetDigest, validateIndexerPartitionPlan, } from "./indexerPartitionPlan.js";
 export type { IndexerMemberDisposition, IndexerPartitionGroup, IndexerPartitionPlan, IndexerPartitionStrategy, } from "./indexerPartitionPlan.js";
 export * from "./indexerPartitionInventory.js";
 export * from "./indexerPartitionConvergence.js";
-export * from "./indexerArtifactDependencies.js";
 export * from "./indexerDependencyView.js";
 export * from "./indexerRunEnvelope.js";
 export * from "./indexerSharedArtifactFingerprint.js";
-export * from "./indexerIncrementalImpact.js";
 export * from "./indexerMainRunProtocol.js";
 export * from "./indexerMainLifecycle.js";
-export * from "./indexerSubjectCatalog.js";
 export * from "./indexerProgramRunProtocol.js";
 export * from "./indexerAgentStepProtocol.js";
 export * from "./indexerSemanticInput.js";
@@ -109,6 +107,7 @@ export type KbPackageDefinition = BasePackageDefinition & {
     navigation: PackageNavigationDefinition;
     distribution?: PackageDistributionDefinition;
     assets?: PackageAssetDefinition;
+    site?: PackageSiteDefinition;
 };
 export type LlmsPackageDefinition = BasePackageDefinition & {
     kind: "package.llms";
@@ -131,6 +130,7 @@ export declare const kbPackage: (definition: {
     navigation?: Partial<PackageNavigationDefinition>;
     distribution?: PackageDistributionDefinition;
     assets?: PackageAssetDefinition;
+    site?: PackageSiteDefinition;
 }) => KbPackageDefinition;
 export declare const llmsPackage: (definition: {
     name: string;
@@ -145,6 +145,6 @@ export { sessionChangeSchema, sessionChangesSchema, readSessionChanges, writeSes
 export type { SessionChange } from "./sessionMetadata.js";
 export { indexerArticleKeySchema, indexerArticlePlanSchema, validateIndexerArticlePlan, indexerArticleSectionKey, validateIndexerPlannedArticles } from "./indexerArticlePlan.js";
 export type { IndexerArticlePlan } from "./indexerArticlePlan.js";
-export * from "./readingStructure.js";
-export * from "./indexerKnowledgeDependency.js";
+export * from "./knowledgeMap.js";
 export * from "./indexerApprovedKnowledge.js";
+export * from "./articleStructure.js";