@c4a/context 0.7.9 → 0.7.10-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/articleStructure.d.ts +254 -0
  2. package/docs/guides/agent-dialogue.md +1 -1
  3. package/docs/guides/code-indexer-skill-authoring.md +76 -178
  4. package/docs/guides/indexer-provider-and-customization.md +93 -453
  5. package/docs/guides/indexer-skill-creation.md +107 -97
  6. package/docs/guides/knowledge-updates.md +35 -14
  7. package/docs/guides/markdown-indexer-skill-authoring.md +57 -134
  8. package/docs/reference/indexer-provider-protocol.md +52 -102
  9. package/docs/reference/package-templates.md +39 -65
  10. package/docs/reference/template-variables.md +2 -3
  11. package/index.d.ts +6 -10
  12. package/index.js +6441 -8771
  13. package/indexerAgentStepProtocol.d.ts +0 -910
  14. package/indexerApprovedKnowledge.d.ts +98 -359
  15. package/indexerArticlePlan.d.ts +3 -26
  16. package/indexerArtifact.d.ts +201 -70
  17. package/indexerArtifactPolicy.d.ts +0 -18
  18. package/indexerArtifactResult.d.ts +240 -888
  19. package/indexerAuthoringFixture.d.ts +0 -13
  20. package/indexerBenchmark.d.ts +2 -2
  21. package/indexerCandidateCompile.d.ts +123 -167
  22. package/indexerCatalogFallback.d.ts +32 -374
  23. package/indexerCollectionMapping.d.ts +2 -2
  24. package/indexerContentLayers.d.ts +187 -41
  25. package/indexerContractOverlay.d.ts +30 -44
  26. package/indexerControlledInvocation.d.ts +6 -6
  27. package/indexerControlledProgram.d.ts +959 -3020
  28. package/indexerDependencyView.d.ts +96 -96
  29. package/indexerEffectiveArtifact.d.ts +381 -242
  30. package/indexerExampleDecision.d.ts +134 -134
  31. package/indexerExampleIdentity.d.ts +6 -6
  32. package/indexerExampleIdentityAudit.d.ts +6 -6
  33. package/indexerInventoryDisposition.d.ts +0 -39
  34. package/indexerLayerComposition.d.ts +1378 -852
  35. package/indexerLayoutChange.d.ts +24 -33
  36. package/indexerLayoutProposalSet.d.ts +143 -137
  37. package/indexerLayoutResolver.d.ts +116 -101
  38. package/indexerLayoutTransition.d.ts +6 -6
  39. package/indexerMainLifecycle.d.ts +1 -11
  40. package/indexerMainRunLedger.d.ts +0 -14
  41. package/indexerMainRunProtocol.d.ts +806 -2530
  42. package/indexerMainWorkset.d.ts +0 -1212
  43. package/indexerNavigationArtifactPlan.d.ts +2 -2
  44. package/indexerOverlayQuestionApplyProposal.d.ts +0 -4
  45. package/indexerParserCoordinate.d.ts +2 -2
  46. package/indexerParserExecutionPlan.d.ts +42 -42
  47. package/indexerPartitionPlan.d.ts +24 -354
  48. package/indexerPhysicalArtifactManifest.d.ts +12 -27
  49. package/indexerPostAuthorComposition.d.ts +2 -253
  50. package/indexerPostAuthorRunLedger.d.ts +860 -562
  51. package/indexerPrimaryProjection.d.ts +2 -2
  52. package/indexerPrimaryResultView.d.ts +0 -318
  53. package/indexerProfileContract.d.ts +200 -549
  54. package/indexerProgramExecutionAuthorization.d.ts +4 -4
  55. package/indexerProgramRunProtocol.d.ts +806 -2527
  56. package/indexerProjectProposal.d.ts +8 -8
  57. package/indexerProjectedArtifactFanOutAudit.d.ts +8 -8
  58. package/indexerProjectedArtifactPlan.d.ts +0 -9
  59. package/indexerProvider.d.ts +46 -288
  60. package/indexerProviderComposition.d.ts +16 -42
  61. package/indexerQuestionAuthority.d.ts +2 -82
  62. package/indexerReaderTargetInventory.d.ts +6 -6
  63. package/indexerRequirementLifecycle.d.ts +6 -6
  64. package/indexerResultReconciliation.d.ts +35 -149
  65. package/indexerSemanticInput.d.ts +10642 -4685
  66. package/indexerStructuredDeclaration.d.ts +24 -24
  67. package/indexerTemplateRendering.d.ts +239 -113
  68. package/knowledgeMap.d.ts +5 -5
  69. package/package.json +1 -1
  70. package/templates/package-templates/kb/skills/knowledge-query/SKILL.md +13 -16
  71. package/templates/package-templates.zh-CN/kb/skills/knowledge-query/SKILL.md +9 -9
  72. package/indexerArtifactDependencies.d.ts +0 -693
  73. package/indexerCompositionFactDependencies.d.ts +0 -16
  74. package/indexerExampleFactDependencies.d.ts +0 -17
  75. package/indexerIncrementalImpact.d.ts +0 -221
  76. package/indexerKnowledgeDependency.d.ts +0 -46
  77. package/indexerSubjectCatalog.d.ts +0 -230
  78. package/indexerSubjectKeyAuthority.d.ts +0 -786
@@ -254,27 +254,19 @@ continue with a warning, and counts above 300 return the non-Gate
254
254
  partial outcome reopens the owning semantic step; it does not create a profile
255
255
  revision ledger or an override route.
256
256
 
257
- Artifact content has three mechanically separate layers. `facts[]` contains
258
- canonical, source-bound values and never reader prose. A structured
259
- `deterministic-block` contains only a registered renderer and `fact_refs`; the
260
- CLI resolves those Facts and derives both Markdown and evidence, so a Provider
261
- cannot relabel arbitrary JSON or prose as a catalog. A `semantic-prose` block
262
- contains evidence-bound Markdown and cannot cite Facts as a way to increase
263
- deterministic coverage. The normalized rendered Section retains ordered
264
- `content_blocks` with the layer, Fact refs, evidence refs and per-block digest;
265
- its Section digest covers that ledger and the exact reader-visible Markdown.
266
-
267
- `ArtifactResult` also carries
268
- `context.indexer.capability-group-evidence/v1`. It repeats the complete member
269
- set bound by the author workset even when no capability group is selected. A
270
- non-empty capability group has a stable ref derived only from the logical unit
271
- and capability key, at least two explicit member-to-evidence bindings, and one
272
- or more actual Artifact Section evidence bindings. A member cannot belong to
273
- two capability groups. Every member evidence ref must be a current Result
274
- evidence binding and must be visible in one of the declared Sections. Unknown
275
- members or Sections, page-level evidence without Section consumption, and
276
- workset/member-set drift are rejected. This protocol does not assign projection
277
- dispositions to members outside capability groups.
257
+ Artifact content contains reader Markdown and actual source-region references.
258
+ Each semantic-prose block supplies at most three positions using `source_ref`
259
+ and a file/line `locator`; the Host verifies the current authorized source and
260
+ computes the region `content_digest`. The limit applies to an output fragment,
261
+ not the whole article. Select necessary references or split the writing by
262
+ meaning; never truncate necessary references or merge disjoint source regions.
263
+ An article has no Fact table, evidence ID table, or per-binding ledger.
264
+ Parser output remains a reading aid, not a required submission representation.
265
+
266
+ The Host retains the current workset's inventory accounting in the internal
267
+ Result. Author supplies member dispositions, not member-to-evidence bindings
268
+ or an independent capability evidence graph. This accounting is not copied
269
+ into the approved article index.
278
270
 
279
271
  ## Full-path example identity
280
272
 
@@ -294,35 +286,14 @@ for the same complete example identity are a hard
294
286
  forge an empty collision list. Candidate disposition and linkage are separate
295
287
  downstream contracts.
296
288
 
297
- ## SubjectKey schema authority
298
-
299
- Community profile identity rules have one authority: the top-level
300
- `subject_key_schemas` array in the CLI profile contract. A community Provider
301
- manifest cannot copy or replace that schema. A namespaced additional profile
302
- has the other allowed authority: the exact owner Provider's
303
- `composition.extensions[].subject_key_schema`. The extension declaration is
304
- required and may use only the CLI's closed namespace/local-key derivation
305
- operators, kind identifiers and normalization rules.
306
-
307
- Final selection resolves both forms to
308
- `context.indexer.resolved-subject-key-schema/v1`. The record binds the Indexer,
309
- profile, base-contract or Provider authority, schema digest and resolution
310
- digest. Its canonical set digest is part of the stable final selection report;
311
- transport paths and runtime receipts are not. Subject keys must match a kind in
312
- the resolved schema and satisfy its normalization before they can become a
313
- canonical NodeRef.
314
-
315
- An unchanged schema is equivalent. Adding a kind while preserving the existing
316
- namespace, normalization and local-key operators is compatible. Removing or
317
- changing an existing identity derivation is identity-breaking: the owning
318
- authority must advance its major version and the schema version must increase.
319
- When approved Nodes exist, Context requires a non-delegable
320
- `confirm-subject-reidentification` authorization bound to the exact old/new
321
- schema digests, approved catalog, complete deterministic mapping and report.
322
- Missing mappings, one old Node mapping to multiple Nodes, multiple old Nodes
323
- colliding on one new Node, stale authorization or digest drift blocks
324
- activation. With no approved Node, the human Gate is omitted but conformance
325
- and major-version checks still apply.
289
+ ## Article identity and source scope
290
+
291
+ Production does not build a subject graph or require SubjectKey schemas.
292
+ Provider extensions declare their reading and writing capabilities without
293
+ namespace/kind normalization or subject re-identification gates. Context keeps
294
+ article identity and fragment identity separately from reader titles and paths.
295
+ Sources remain registered and authorized; removing graph modeling does not
296
+ permit reading an undeclared source or changing another article's identity.
326
297
 
327
298
  ## Requirement change authority
328
299
 
@@ -423,7 +394,7 @@ identity, operations, scopes, profile composition, requirement bindings, owner
423
394
  closure and read authority are byte-identical. It revalidates overlay
424
395
  conformance,
425
396
  reuses the exact staged Bundles, and reruns both static and final selection
426
- against the target requirement digest. Provider and SubjectKey authority must
397
+ against the target requirement digest. Provider authority must
427
398
  remain unchanged. Final selection resolves every CLI-base question back to its
428
399
  exact selected profile contract and requires one current validation proof
429
400
  for every overlay question; forged bindings and duplicate, stale, or unused
@@ -431,7 +402,7 @@ proofs fail before the final report is issued. The report binds the resulting
431
402
  question authority set digest. The resulting
432
403
  `context.indexer.overlay-question-registry-apply-proposal/v1` contains the full
433
404
  target `src/indexers.yaml` snapshot and binds the amendment, confirmation,
434
- overlay validation, rebound selection, SubjectKey schema set and finalized reports.
405
+ overlay validation, rebound selection and finalized reports.
435
406
  The proposal goes through the same `stage-indexer-project-proposal` and
436
407
  `apply-indexer-project` Actions as ordinary registry/customization proposals.
437
408
  The latter dispatches this typed proposal to one expected-base CAS, project
@@ -442,15 +413,12 @@ temporary Provider path.
442
413
 
443
414
  ## Controlled invocation
444
415
 
445
- Author result acceptance checks the actual task, source/module, subject and
446
- Provider layer. Provider integrity, bundle/config/customization fingerprints
447
- remain recorded metadata, not byte-equality gates between a resumed request and
448
- its result. Selected Facts are resolved by their supplied identity and source
449
- references; their current values are recorded without comparing a previous
450
- parser payload digest. Source-span line ranges may expand within the same file
451
- content. Structured declarations resolve actual file/item identities, not a
452
- previous inventory or signature fingerprint. Source file content checks,
453
- unknown-reference rejection and atomic write protection remain in force.
416
+ Author result acceptance checks the actual task, source/module and selected
417
+ Provider authority, including its current bundle and configuration. Article
418
+ content supplies actual source regions, not selected Fact IDs or structured
419
+ claim ledgers. The Host computes region fingerprints from the current captured
420
+ text. Unknown or unauthorized paths, source-version drift and write conflicts
421
+ remain errors.
454
422
 
455
423
  These continuation rules do not relax executable program authorization or allow
456
424
  an Agent to select undeclared sources.
@@ -577,24 +545,18 @@ may route different Sections to different collections only by declaring
577
545
  separate Artifacts in its validated Bundle; the CLI does not silently split or
578
546
  merge reader pages to repair a Provider Result.
579
547
 
580
- The compile-internal resolver emits `context.indexer.layout-proposal/v1`. It
581
- binds the exact Artifact Result, profile contract, validated SubjectKey schema
582
- set and exact schema digest, Indexer and source. The resolver validates the
583
- SubjectKey against the selected schema normalization before deriving NodeRef;
584
- a caller-supplied digest is not accepted as schema authority. NodeRef plus the
585
- logical Artifact id/kind derives ArtifactRef. NodeRef, owner Indexer, Artifact
586
- kind and Section key derive a stable logical Section identity; its placement
587
- under one Artifact derives SectionRef. This lets a diff distinguish a moved
588
- Section from new content without allowing the same logical Section to have two
589
- primary placements. The ViewRef is an internal projection. Output paths are
590
- derived under `knowledge/<collection>/` and never accepted from a Provider.
548
+ The compile-internal resolver emits `context.indexer.layout-proposal/v1`.
549
+ It binds the accepted Result, profile contract, Indexer and source. A stable
550
+ article reference derives from the accepted writing group and artifact identity;
551
+ the fragment key belongs to that article. There is no independent Node or View
552
+ identity. Output paths live under `knowledge/<collection>/`; layout validates
553
+ article ownership, fragment placement and path collisions before writing.
591
554
 
592
555
  Template Artifacts enter layout only after validated rendering. Only rendered
593
556
  Sections exist; an omitted optional projection does not create an empty
594
557
  Section, while a retained material gap remains unresolved without
595
558
  reader-visible placeholder content. Artifact Bundle purpose and `split_of`
596
- lineage are retained in the proposal. A proposal set rejects duplicate Node
597
- owners, Artifact identities, logical Section identities, Section placements
559
+ lineage are retained in the proposal. A proposal set rejects duplicate Artifact identities, logical Section identities, Section placements
598
560
  and output paths across Indexers, as well as missing, nested or kind-changing
599
561
  semantic-split parents.
600
562
 
@@ -779,24 +741,16 @@ a rendered byte budget. Every body Section uses exact markers:
779
741
  <!-- /context:indexer-section -->
780
742
  ```
781
743
 
782
- Only `{{variable:<id>}}` and `{{block:<id>}}` are accepted. Direct variables are
783
- semantic prose. A block source variable is a deterministic Fact projection,
784
- must bind canonical `fact_refs`, and must equal the CLI's normalized projection
785
- of those Facts. Blocks select one of
786
- the CLI-owned `bullet-list`, `key-value-table`, `json-code-block` or `public-contract-table` renderers;
787
- templates cannot register code or helpers. A block directive occupies its own
788
- template line so the renderer can retain an exact content-layer boundary. The
789
- contract and body must declare exactly the same Sections and placeholders.
790
-
791
- `ArtifactResult` binds every template variable to current evidence refs and
792
- binds every declared Section to `section_key`, owner Indexer, document kind,
793
- reader goal and Artifact kind. Rendering validates the Provider/customization
794
- fingerprints, template digest, current CLI-owned applicability conditions,
795
- variable types and expansion limits, per-variable evidence boundary and exact
796
- CLI-owned question target. An optional Section without data
797
- or sufficient evidence is absent from the rendered Candidate. A required
798
- Section in the same state becomes the already-declared material-question
799
- transition and makes `review_ready` false.
744
+ Only `{{variable:<id>}}` and `{{block:<id>}}` are accepted. Variables carry
745
+ their declared typed values and actual source-region references. Registered
746
+ block renderers format those values; authors do not construct canonical Fact
747
+ records or bind Fact IDs. Templates cannot register executable helpers.
748
+ The contract and body must declare the same sections and placeholders.
749
+
750
+ `ArtifactResult` binds each fragment to its owner and article classification.
751
+ Rendering validates the current template, variable types and expansion limits.
752
+ Optional sections without data are omitted; an unresolved required section
753
+ uses the existing material-question path rather than fabricated prose.
800
754
 
801
755
  Context validates template-program directives, declared variable types and
802
756
  expansion limits before rendering. Supplied variable values and Section prose
@@ -810,13 +764,9 @@ digests. Deterministic blocks contribute catalog completeness but never
810
764
  semantic-prose density. Later `build` projects this approved body; it does not
811
765
  perform a first render or change its structure.
812
766
 
813
- An ArtifactResult may emit
814
- `context.indexer.structured-claim-set/v1`. Every claim binds a stable claim
815
- kind and subject to one real Artifact/Section owner and one or more evidence
816
- refs carried by that exact Section. The subject must be the current logical
817
- unit, one of its CLI-owned inventory members, or an authorized target-resolution
818
- identity. Missing owners, outside subjects, unknown evidence and evidence that
819
- is known globally but absent from the owner Section all fail Result validation.
767
+ Articles do not submit structured claims, subject identities or evidence-binding
768
+ tables. Actual source references support traceability and change detection;
769
+ their existence does not prove semantic correctness.
820
770
 
821
771
  Main-run validation does not produce a prose-quality audit. Content usefulness,
822
772
  completeness and faithfulness belong to the existing Agent or user Review.
@@ -839,16 +789,16 @@ in knowledge frontmatter and is not proof that remaining material is useful.
839
789
  ## Incremental planning handoff
840
790
 
841
791
  A semantic Partition group may declare `ready_for_author: true` when the Agent
842
- has resolved its subject, primary ownership, reader task and shared dependencies.
792
+ has resolved the writing boundary, primary ownership, reader task and shared dependencies.
843
793
  The CLI can then deliver an initial wave before all Partition tasks are accepted.
844
794
  This is an optional scheduling declaration, not a new evidence or approval gate.
845
795
  Absent/false groups wait; every inventory member still needs a final disposition.
846
796
  The original Partition ledger resumes after normal structure review, Author,
847
797
  Composer, content Review, close and successful build. Later material for the same
848
- subject reuses its page identity and approved prose. A wave finishing never means
798
+ article reuses its identity and approved prose. A wave finishing never means
849
799
  the remaining source scope is complete.
850
800
 
851
801
  Known code-symbol planning views provide member overviews with immutable full
852
802
  fact links and bounded captured-source access. Providers must inspect details
853
803
  when semantic boundaries are uncertain; unknown payload formats retain full
854
- reading. Author receives full selected facts and source material.
804
+ reading. Author reads the selected source material and cites the regions actually used.
@@ -232,19 +232,15 @@ rejects it.
232
232
  The default kb template includes:
233
233
 
234
234
  - `skills/knowledge-query/SKILL.md`, a reusable skill that teaches agents to
235
- query copied knowledge pages structure-first, cite page/section evidence, use
236
- `context-build-inventory.json` edge records for package-visible
237
- relationships, and report gaps instead of inventing unsupported answers. The
238
- build inventory also exposes `structure.relationship_coverage` so a consumer
239
- can distinguish an observed zero-edge result from unknown relationship
240
- coverage. The
235
+ navigate copied knowledge pages, cite relevant text and its exported source
236
+ attribution, and report gaps instead of inventing unsupported answers. The
241
237
  default entry OKF root is `wikis/`; packages that select additional internal
242
238
  collections expose
243
239
  `guides/`, `rules/`, or `feats/` indexes when those roots are selected.
244
240
  - `skills/knowledge-query/scripts/search.mjs`, a dependency-free BM25 fallback
245
241
  for exact terms, mixed keyword queries, and large Markdown indexes. It chunks
246
242
  mechanically, returns inspectable paths and line ranges, and never replaces
247
- source-backed relationship evidence.
243
+ reading the relevant source-backed explanation.
248
244
  - `wikis/index.md`, the editable OKF bundle entry page for the generated
249
245
  `dist/<package-name>/wikis/` directory.
250
246
 
@@ -261,10 +257,8 @@ The generated
261
257
  KB entry surface. Internal collections are mapped into OKF roots during build:
262
258
  `codeindex`, `business`, and `product` go to `wikis/`; `architecture`, `sop`,
263
259
  `faq`, `decision`, and `incident` go to `guides/`; `standards` and `test` go to
264
- `rules/`; and `feats` goes to `feats/`. Treat `wikis/` as the structured
265
- entity-and-relationship layer. Guides and rules may explain, operationalize,
266
- or constrain that knowledge, but directory placement alone does not establish
267
- a relationship.
260
+ `rules/`; and `feats` goes to `feats/`. These roots organize articles by content
261
+ type; directory placement does not establish a relationship or a subject graph.
268
262
 
269
263
  Default navigation rules:
270
264
 
@@ -307,54 +301,36 @@ wants project-specific behavior beyond knowledge lookup.
307
301
 
308
302
  ## Context OKF Profiles
309
303
 
310
- Approved Markdown under `knowledge/` and its deterministic
311
- `knowledge/structure.yaml` projection form the authoring source of truth:
312
-
313
- - top-level YAML frontmatter uses OKF fields such as `type`, `title`,
314
- `description`, `tags`, `timestamp`, and `resource`;
315
- - each Markdown page keeps reader fields, stable page identity, `sources`, and a
316
- small recovery capsule (`resource`, `node_type`, containment fields, and
317
- relationship mode);
318
- - large or repeated machine state such as complete `code_symbols`, code
319
- evidence, relationship records, candidate fingerprints, and optimization
320
- decisions lives once in the corresponding `structure.yaml` view record;
321
- - Context readers hydrate that machine state in memory before verify, audit,
322
- revision, or build. Do not copy a compact page as a new page without using a
323
- Context authoring command;
324
- - do not nest Context production metadata under `context`; fields such as
325
- `context.sources` and `context.code_symbols` are not accepted production fields;
326
- - section provenance lives in `<!-- context:section ... source_ref="..." -->`
327
- comments. When a Section needs more than one citation, the CLI preserves the
328
- complete set in its adjacent `context:source_refs` block;
329
- - do not add frontmatter `source_refs`; page-level provenance is derived from
330
- section source refs when needed;
331
- - do not add `context` or `schema` fields.
332
-
333
- Package knowledge pages under `dist/<package-name>/` use a consumer projection.
334
- They retain reader-facing fields such as `title`, `type`, `description`, `tags`,
335
- `timestamp`, and custom non-lifecycle fields. Node identity, `resource`,
336
- `sources`, Section evidence comments, and build-only fields are omitted from the
337
- page. `context-build-inventory.json` records the distributed path, approved
338
- knowledge path, node identity, source summary, and package-visible structure.
339
- Maintainers return to the mapped `knowledge/` page for exact `sources` and
340
- `source_ref` attribution. `knowledge/` is never rewritten by this projection.
341
-
342
- Accepted section `source_ref` forms:
343
-
344
- ```text
345
- src-N#symbol:<file>:<symbol-id>:<kind>@<digest>
346
- src-N#span:<heading-hint> L<start>-<end>@<span-hash>
347
- ```
348
-
349
- The code symbol form includes the source-relative file so same-name symbols in
350
- different files resolve to one exact symbol-index row. Consumers should still
351
- treat the complete `source_ref` as opaque. Production pages do not expose
352
- Candidate fingerprints, Indexer digests, or `code_origin`.
353
-
354
- `#span:` refs retain source snapshot line ranges for human review, diffing, and
355
- stable re-pinning. They resolve against the stored file/Lark snapshot or the saved
356
- Note/Sessions Markdown, not the code symbol index. A session's optional commit/MR
357
- association stays in its source file; knowledge does not duplicate those fields.
304
+ Approved Markdown under `knowledge/` and the article index in
305
+ `knowledge/structure.yaml` have separate responsibilities:
306
+
307
+ - Markdown owns `title`, `type`, `description` and the ISO UTC `timestamp`.
308
+ `resource` and `tags` are optional reader metadata, not required identities.
309
+ - Structure owns stable `article_id`, `path`, `collection`, `visibility`,
310
+ and fragment `sections` with their region `references`.
311
+ - Markdown fragment markers contain only their stable ID:
312
+ `<!-- context:section id="usage" -->` and `<!-- /context:section -->`.
313
+ Structure records each corresponding ID and at most three source positions
314
+ per fragment, not three per article.
315
+ - A reference contains `source_ref`, `locator: { path, start_line, end_line }`
316
+ and the Host-computed regional `content_digest`. Do not duplicate this in
317
+ Markdown frontmatter or comments.
318
+ - Neither Markdown nor structure keeps a node graph, parser fact ledger,
319
+ evidence-binding table or a second copy of article prose.
320
+ - Article moves retain identity through Context's existing revision workflow.
321
+ Direct Markdown copies alone do not include complete provenance.
322
+
323
+ Package pages under `dist/<package-name>/` retain reader metadata and receive
324
+ a generated Sources section derived from the article references and source
325
+ registry. Repository links include file and line ranges; document links retain
326
+ the captured document attribution. This export does not rewrite `knowledge/`.
327
+ The build inventory maps exported pages back to their approved article paths.
328
+
329
+ Source snapshots and regional baselines remain machine-managed. Update checks
330
+ compare cited regions, relocating unchanged text only when its new position is
331
+ unambiguous. Missing, changed or ambiguous regions require review; an unchanged
332
+ region does not prove that uncited new material is irrelevant. A session's
333
+ optional commit/MR association stays with its source document.
358
334
 
359
335
  The kb package root may contain agent files such as `AGENTS.md` and `skills/`.
360
336
  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
377
353
  file includes `selected_by` entries such as `{ "kind": "collection" }`,
378
354
  `{ "kind": "okf_root" }`, `{ "kind": "include" }`, or `{ "kind": "default" }`,
379
355
  and a `production_metadata` object for selected page-level production fields.
380
- Child and relationship records use the inventory's canonical structure
381
- projection. The inventory exposes package-visible typed
382
- edges under `structure.edge_records`; these records are filtered to edges whose
383
- endpoints are present in the selected package. Use those edge records for
384
- relationship citations inside the package instead of assuming the workspace
385
- `knowledge/structure.yaml` file is bundled.
356
+ The `structure.articles` projection retains selected article identities and
357
+ fragment source references. It does not contain graph nodes or typed edges.
358
+ Published Markdown includes readable source attribution derived from these
359
+ references; the Agent does not maintain a second source list in the page.
386
360
 
387
361
  For KB packages, the inventory records `package.distribution` as
388
362
  `layout: "flat"`, `knowledge_namespace: null`, and the four package-relative
@@ -135,13 +135,12 @@ Each item contains:
135
135
  | `sourcePath` | Approved knowledge path before OKF output mapping, for example `architecture/entity/button.md`. |
136
136
  | `approved_path` | Alias for `sourcePath`. |
137
137
  | `dist_path` | Alias for `path`. |
138
+ | `article_id` | Stable article identity from the approved article index. |
138
139
  | `internalCollection` | Internal approved collection, for example `architecture`. |
139
140
  | `internal_collection` | Alias for `internalCollection`. |
140
141
  | `collection` | Internal approved collection; alias for `internalCollection`. |
141
142
  | `okf_root` | OKF output root, for example `wikis`, `guides`, `rules`, or `feats`. |
142
143
  | `okf_root_path` | Final flat package-relative OKF root. |
143
- | `node_ref` | Stable NodeRef from approved frontmatter, for example `entity/button`. |
144
- | `view_ref` | Stable ViewRef from approved frontmatter, for example `architecture:entity/button`. |
145
144
  | `pathWithinCollection` | Path below the OKF root, for example `architecture/entity/button.md`. |
146
145
  | `href` | Link relative to the template file currently being rendered. Use this in custom templates. |
147
146
  | `hrefFromTemplate` | Alias for `href`. |
@@ -151,7 +150,7 @@ Each item contains:
151
150
  | `type` | OKF `type` from frontmatter. |
152
151
  | `description` | OKF `description` from frontmatter, when present. |
153
152
  | `timestamp` | OKF `timestamp` from frontmatter, when present. |
154
- | `source` | First top-level `sources` entry without the `repo:` prefix, or the group name. |
153
+ | `source` | First actual source reference from the article index, or the group name. |
155
154
  | `group` | First path segment under the OKF root. |
156
155
  | `parentPath` | Parent path below the OKF root. |
157
156
  | `depth` | Segment count below the OKF root. |
package/index.d.ts CHANGED
@@ -18,8 +18,8 @@ export type { ExpectedProviderResolution, IndexerCliReleaseManifest, IndexerHost
18
18
  export * from "./indexerProviderComposition.js";
19
19
  export * from "./indexerProviderSelectionProposal.js";
20
20
  export * from "./indexerCustomizationLadder.js";
21
- export { indexerMetricContractSchema, indexerArtifactPolicyVariantSchema, indexerInventoryDomainSchema, indexerOperatorContractDigest, indexerOperatorContractSchema, indexerProfileContractDigest, indexerProfileContractEntrySchema, indexerProfileContractSchema, indexerProfileSubjectKeySchema, indexerQuestionTargetDomainSchema, indexerReaderQuestionContractSchema, indexerSubjectKeyContractSchema, inflationSensitiveHardMaximum, validateIndexerOperatorContract, validateIndexerProfileContract, } from "./indexerProfileContract.js";
22
- export type { IndexerMetricContract, IndexerOperatorContract, IndexerProfileContract, IndexerProfileContractEntry, IndexerProfileSubjectKey, IndexerReaderQuestionContract, IndexerSubjectKeyContract, } from "./indexerProfileContract.js";
21
+ export { indexerMetricContractSchema, indexerArtifactPolicyVariantSchema, indexerInventoryDomainSchema, indexerOperatorContractDigest, indexerOperatorContractSchema, indexerProfileContractDigest, indexerProfileContractEntrySchema, indexerProfileContractSchema, indexerQuestionTargetDomainSchema, indexerReaderQuestionContractSchema, inflationSensitiveHardMaximum, validateIndexerOperatorContract, validateIndexerProfileContract, } from "./indexerProfileContract.js";
22
+ export type { IndexerMetricContract, IndexerOperatorContract, IndexerProfileContract, IndexerProfileContractEntry, IndexerReaderQuestionContract, } from "./indexerProfileContract.js";
23
23
  export { createIndexerOverlayValidationReceipt, indexerContractOverlayDigest, indexerContractOverlaySchema, indexerOverlayValidationReceiptDigest, indexerOverlayValidationReceiptSchema, validateIndexerContractOverlay, validateIndexerOverlayValidationReceipt, } from "./indexerContractOverlay.js";
24
24
  export type { IndexerContractOverlay, IndexerOverlayConformanceReport, IndexerOverlayValidationReceipt, } from "./indexerContractOverlay.js";
25
25
  export * from "./indexerOverlayQuestionAmendment.js";
@@ -30,23 +30,19 @@ export type { IndexerEvidenceRef, IndexerLayerCompositionInput, IndexerLayerFrag
30
30
  export * from "./indexerArtifact.js";
31
31
  export { canonicalIndexerNodeRef, indexerSubjectKeySchema, } from "./indexerSubjectIdentity.js";
32
32
  export type { IndexerSubjectKey } from "./indexerSubjectIdentity.js";
33
- export * from "./indexerSubjectKeyAuthority.js";
34
33
  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";
35
- export type { IndexerComposedResultEnvelope, IndexerComposerInvocationReceipt, IndexerEffectiveComposer, IndexerEffectiveComposerSet, IndexerEffectiveArtifactSet, IndexerLayerFragmentRunResult, IndexerPostAuthorFragmentRequest, IndexerPostAuthorPlan, IndexerPostAuthorWorkset, IndexerPostAuthorWorksetSet, IndexerPrimaryArtifactView, IndexerPrimaryFactView, IndexerPrimaryResultView, } from "./indexerPostAuthorComposition.js";
36
- export { buildIndexerMainWorkset, buildIndexerMainWorksetSet, buildIndexerRepairIntent, buildIndexerMainTransportBatch, buildIndexerTargetResolutionView, indexerMainWorksetDigest, indexerMainWorksetSchema, indexerMainWorksetSetDigest, indexerMainWorksetSetSchema, indexerMainTransportBatchSchema, indexerOwnerCohortRef, indexerTargetResolutionViewDigest, indexerTargetResolutionViewSchema, validateIndexerMainWorkset, validateIndexerMainWorksetSet, validateIndexerRepairIntent, validateIndexerTargetResolutionView, } from "./indexerMainWorkset.js";
37
- export type { IndexerMainAuthorWorkset, IndexerMainPartitionWorkset, IndexerMainWorkset, IndexerMainWorksetSet, IndexerRepairIntent, IndexerMainTransportBatch, IndexerTargetResolutionView, } from "./indexerMainWorkset.js";
34
+ export type { IndexerComposedResultEnvelope, IndexerComposerInvocationReceipt, IndexerEffectiveComposer, IndexerEffectiveComposerSet, IndexerEffectiveArtifactSet, IndexerLayerFragmentRunResult, IndexerPostAuthorFragmentRequest, IndexerPostAuthorPlan, IndexerPostAuthorWorkset, IndexerPostAuthorWorksetSet, IndexerPrimaryArtifactView, IndexerPrimaryResultView, } from "./indexerPostAuthorComposition.js";
35
+ export { buildIndexerMainWorkset, buildIndexerMainWorksetSet, buildIndexerRepairIntent, buildIndexerMainTransportBatch, indexerMainWorksetDigest, indexerMainWorksetSchema, indexerMainWorksetSetDigest, indexerMainWorksetSetSchema, indexerMainTransportBatchSchema, indexerOwnerCohortRef, validateIndexerMainWorkset, validateIndexerMainWorksetSet, validateIndexerRepairIntent, } from "./indexerMainWorkset.js";
36
+ export type { IndexerMainAuthorWorkset, IndexerMainPartitionWorkset, IndexerMainWorkset, IndexerMainWorksetSet, IndexerRepairIntent, IndexerMainTransportBatch, } from "./indexerMainWorkset.js";
38
37
  export { indexerPartitionGroupBindingDigest, indexerPartitionGroupProjectionDigest, indexerPartitionPlanBindingDigest, indexerPartitionPlanCanonicalHash, indexerPartitionPlanSchema, indexerPartitionStrategySchema, indexerPartitionStrategySetDigest, validateIndexerPartitionPlan, } from "./indexerPartitionPlan.js";
39
38
  export type { IndexerMemberDisposition, IndexerPartitionGroup, IndexerPartitionPlan, IndexerPartitionStrategy, } from "./indexerPartitionPlan.js";
40
39
  export * from "./indexerPartitionInventory.js";
41
40
  export * from "./indexerPartitionConvergence.js";
42
- export * from "./indexerArtifactDependencies.js";
43
41
  export * from "./indexerDependencyView.js";
44
42
  export * from "./indexerRunEnvelope.js";
45
43
  export * from "./indexerSharedArtifactFingerprint.js";
46
- export * from "./indexerIncrementalImpact.js";
47
44
  export * from "./indexerMainRunProtocol.js";
48
45
  export * from "./indexerMainLifecycle.js";
49
- export * from "./indexerSubjectCatalog.js";
50
46
  export * from "./indexerProgramRunProtocol.js";
51
47
  export * from "./indexerAgentStepProtocol.js";
52
48
  export * from "./indexerSemanticInput.js";
@@ -150,5 +146,5 @@ export type { SessionChange } from "./sessionMetadata.js";
150
146
  export { indexerArticleKeySchema, indexerArticlePlanSchema, validateIndexerArticlePlan, indexerArticleSectionKey, validateIndexerPlannedArticles } from "./indexerArticlePlan.js";
151
147
  export type { IndexerArticlePlan } from "./indexerArticlePlan.js";
152
148
  export * from "./knowledgeMap.js";
153
- export * from "./indexerKnowledgeDependency.js";
154
149
  export * from "./indexerApprovedKnowledge.js";
150
+ export * from "./articleStructure.js";