@c4a/context 0.7.43 → 0.7.50

package/docs/guides/knowledge-updates.md

@@ -18,6 +18,17 @@ actual behavior, a confirmed decision, and a proposal that is not implemented.
 
 ## Keep planning local to the change
 
+Same-repository originals use `repo-content.yaml` rather than another capture.
+For editing/registering them, use the `context-repo-content` Skill without
+starting production. An explicitly requested source update can select
+`repo-content:<entry-id>` in its confirmed requirement and update scope. The
+prepared update includes current local changes and chapter impact candidates.
+Docs compare cited regions; Skills compare the whole owning Skill directory,
+including untracked additions. Missing historical objects are unknown, not an
+empty diff. Inspect/edit does not advance references; delivery or an explicit
+no-impact outcome settles the selected scope. Historical locators always store
+the real repository path at the cited commit, not today's registration path.
+
 Before starting production, compare the proposed content with the workspace's
 reader purpose. For clearly unrelated anecdotes or personal rankings, briefly
 recommend leaving them out of the formal manual or saving them separately because

package/docs/guides/package-outputs.md

@@ -17,6 +17,11 @@ package index, and section fingerprint rebuilds are not current close output.
 
 ## Default New-Workspace Outputs: Knowledge Base + Website
 
+Same-repository originals have an optional [repository entrance](repo-content.md):
+`repoContentPage: true` in a KB declaration projects README and Skill summaries,
+not the full document tree. It does not expose that page on a configured website;
+use `repoContentPage: { site: true }` to opt in. Existing declarations are kept.
+
 Output channels support multiple selection. In a new workspace without explicit
 preferences, the Agent proposes and configures KB + website as the default. Honor
 user feedback, session authority and existing workspace declarations; LLMS is an

package/docs/guides/repo-content.md

@@ -0,0 +1,71 @@
+# Same-repository content
+
+Keep project documentation and authored Skills at their original locations.
+Context registers an entrance without copying their bodies to knowledge or
+source snapshots. For selection and editing use `context-repo-content`.
+
+At the Context workspace root, create `repo-content.yaml`:
+
+```yaml
+protocol: context.repo-content/v1
+entries:
+  docs:
+    kind: docs
+    path: docs
+  tools:
+    kind: skills
+    path: .agents/skills
+```
+
+Paths are Git-root-relative, not workspace-relative. Kinds are `docs`,
+`document`, `skills`, and `skill`. Optional `group` is one module level;
+`mount` overrides the default `[group/]<basename>`. Optional `exclude` globs
+are relative to the entry; they are not access control. Overlapping entries,
+outside targets, nested repositories and cycles are rejected.
+
+`context source ensure repo-content --format json` maintains relative symlinks
+in `repo-content/`; `source inspect repo-content` and `status` inspect without
+repairing. Ordinary files are not overwritten. With disabled symlinks, search
+real paths from the registry rather than reading Git placeholders. No Git
+configuration or index is changed. Registry and relative links can be committed
+by the user; originals remain the only authoring location.
+
+Invalid registration is advisory in `status` and automatic pre-operation link
+maintenance: correct `repo-content.yaml`; existing links are left unchanged.
+The repair command is suggested only for missing or misdirected symlinks, not
+invalid registration, missing targets, ordinary-file conflicts or disabled
+symlinks. Fix those reported conditions rather than repeatedly running ensure.
+Explicit repository-content updates and `context build` require valid
+registration. An invalid registry stops build before replacing existing package
+outputs; it is not treated as an empty registry. Missing source files and
+unavailable Git objects follow the documented fallback behavior instead.
+
+Article navigation uses `[Guide](context:repo/docs/guide.md)`. Build projects
+this to an upstream link when available, otherwise a plain location. Evidence
+instead records `repo-content:docs@<full-commit>` plus real historical path,
+line range and content digest. Uncommitted evidence uses `<commit>+worktree`.
+The evidence Wasm supports these references without treating their existence
+as proof that the source was read in the current query.
+
+## Optional entrance page
+
+```ts
+kbPackage({
+  name: "project-kb",
+  template: { path: "src/package-templates/kb" },
+  repoContentPage: true,
+});
+```
+
+SDK default is off. New initialization with an existing nonempty registry
+creates a KB declaration with the entrance enabled; existing declarations are
+preserved. It projects a group's README and Skill names/descriptions under
+`wikis/repo-content.md` and optional group pages, not all docs or Skill scripts.
+HEAD objects are preferred without network fetching, with declared worktree
+fallback when unavailable. Review README sensitivity before exposing it.
+With a configured website, `{ site: true }` opts into a top-level site entrance;
+plain `true` keeps these pages out of the site.
+
+Other repositories and externally installed Skills are not same-repository
+content. Registering an entrance does not imply installation, execution,
+production or publication authority.

package/index.d.ts

@@ -5,6 +5,7 @@ import type { PackageNavigationDefinition, PackageSelectDefinition } from "./con
 import type { PhaseDefinition, PhaseResourceReference } from "./phases.js";
 import type { ProjectSourceDefinition } from "./sources.js";
 export * from "./indexerCoreExports.js";
+export { repoContentRegistrySchema, repoContentEntrySchema, repoContentPathSchema, repoContentMount, parseRepoContentRef, repoContentScopeMatches, type RepoContentEntry, type RepoContentRegistry } from "./repoContent.js";
 export { indexerComposerContractSchema, indexerComposerDeclarationSchema, indexerExecutionSchema, indexerProviderLayerFragmentSchema, indexerProviderManifestSchema, indexerProviderOperationSchema, indexerToolSourceDeclarationSchema, isIndexerLayerFragmentKind, isIndexerProviderProtocol, loadIndexerProviderManifest, parseIndexerProviderManifest, } from "./indexerProvider.js";
 export type { IndexerComposerContract, IndexerComposerDeclaration, IndexerExecution, IndexerProviderLayerFragment, IndexerProviderManifest, IndexerProviderOperation, IndexerToolSourceDeclaration, } from "./indexerProvider.js";
 export { canonicalOwnerCellRef, indexRequirementSchema, indexRequirementSetSchema, indexerRegistryDigests, indexerDistributionSchema, indexerRegistryEntrySchema, indexerRegistrySchema, loadIndexerRegistry, parseIndexerRegistry, requirementSetFromRegistry, validateFinalizedIndexerRegistry, } from "./indexerRegistry.js";
@@ -109,6 +110,9 @@ export type KbPackageDefinition = BasePackageDefinition & {
     distribution?: PackageDistributionDefinition;
     assets?: PackageAssetDefinition;
     site?: PackageSiteDefinition;
+    repoContentPage?: boolean | {
+        site: true;
+    };
 };
 export type LlmsPackageDefinition = BasePackageDefinition & {
     kind: "package.llms";
@@ -132,6 +136,9 @@ export declare const kbPackage: (definition: {
     distribution?: PackageDistributionDefinition;
     assets?: PackageAssetDefinition;
     site?: PackageSiteDefinition;
+    repoContentPage?: boolean | {
+        site: true;
+    };
 }) => KbPackageDefinition;
 export declare const llmsPackage: (definition: {
     name: string;

package/index.js

@@ -22134,6 +22134,38 @@ function validateCurrentIndexerBenchmarkReport(input) {
   }
   return report;
 }
+// src/repoContent.ts
+var repoContentPathSchema = exports_external.string().min(1).refine((value) => !/[\\\u0000-\u001f\u007f:]/u.test(value) && value.split("/").every((part) => part !== "" && part !== "." && part !== ".." && part.toLowerCase() !== ".git"), "Use a repository-relative path without traversal or .git components");
+var segment = exports_external.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u);
+var repoContentEntrySchema = exports_external.object({
+  kind: exports_external.enum(["docs", "skills", "document", "skill"]),
+  path: repoContentPathSchema,
+  exclude: exports_external.array(exports_external.string().min(1)).optional(),
+  group: segment.optional(),
+  mount: repoContentPathSchema.optional(),
+  title: exports_external.string().min(1).optional(),
+  description: exports_external.string().optional()
+}).strict();
+var repoContentRegistrySchema = exports_external.object({
+  protocol: exports_external.literal("context.repo-content/v1"),
+  entries: exports_external.record(segment, repoContentEntrySchema)
+}).strict();
+function repoContentMount(entry) {
+  return entry.mount ?? [entry.group, entry.path.split("/").at(-1)].filter(Boolean).join("/");
+}
+function parseRepoContentRef(value) {
+  const match = /^repo-content:([A-Za-z0-9][A-Za-z0-9._-]*)(?:@([a-fA-F0-9]{40}(?:[a-fA-F0-9]{24})?)(\+worktree)?)?$/u.exec(value);
+  if (!match)
+    return;
+  return { id: match[1], ...match[2] ? { commit: match[2] } : {}, worktree: !!match[3] };
+}
+function repoContentScopeMatches(scope, reference) {
+  if (scope === reference)
+    return true;
+  const selected = parseRepoContentRef(scope);
+  const cited = parseRepoContentRef(reference);
+  return !!selected && !selected.commit && !!cited && selected.id === cited.id;
+}
 // src/indexerRequirementComparison.ts
 function setRelation(oldValues, newValues) {
   const oldContained = [...oldValues].every((value) => newValues.has(value));
@@ -32170,7 +32202,7 @@ var normalizePackageDistribution = (distribution) => {
   }
   const knowledgeNamespace = distribution.knowledgeNamespace.trim();
   const segments = knowledgeNamespace.split("/");
-  if (knowledgeNamespace.length > PACKAGE_KNOWLEDGE_NAMESPACE_MAX_LENGTH || segments.length === 0 || segments.some((segment) => segment.length > PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_MAX_LENGTH || !PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_PATTERN.test(segment))) {
+  if (knowledgeNamespace.length > PACKAGE_KNOWLEDGE_NAMESPACE_MAX_LENGTH || segments.length === 0 || segments.some((segment2) => segment2.length > PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_MAX_LENGTH || !PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_PATTERN.test(segment2))) {
     throw new TypeError(`Package distribution.knowledgeNamespace must contain safe lowercase path segments using letters, numbers, hyphens, or dots, separated by "/", and be at most ${PACKAGE_KNOWLEDGE_NAMESPACE_MAX_LENGTH} characters: ${distribution.knowledgeNamespace}`);
   }
   return { knowledgeNamespace };
@@ -32238,7 +32270,7 @@ var createPackageDefinitionBase = (kind, definition) => {
   }
   const select = normalizeSelect(definition.select);
   const acronymSegments = new Set(["ai", "api", "cli", "db", "id", "kb", "llm", "llms", "sdk", "ui"]);
-  const defaultDisplayName = definition.name.replace(/[._-]+/gu, " ").trim().replace(/\b[a-z0-9]+\b/gu, (segment) => acronymSegments.has(segment) ? segment.toUpperCase() : `${segment.slice(0, 1).toUpperCase()}${segment.slice(1)}`);
+  const defaultDisplayName = definition.name.replace(/[._-]+/gu, " ").trim().replace(/\b[a-z0-9]+\b/gu, (segment2) => acronymSegments.has(segment2) ? segment2.toUpperCase() : `${segment2.slice(0, 1).toUpperCase()}${segment2.slice(1)}`);
   const builtInVars = {
     displayName: defaultDisplayName.length > 0 ? defaultDisplayName : definition.name,
     packageName: definition.name,
@@ -32274,13 +32306,20 @@ var kbPackage = (definition) => {
   const distribution = normalizePackageDistribution(definition.distribution);
   const assets = normalizePackageAssets(definition.assets);
   const site = normalizePackageSite(definition.site);
+  if (definition.repoContentPage !== undefined && typeof definition.repoContentPage !== "boolean" && (!definition.repoContentPage || typeof definition.repoContentPage !== "object" || definition.repoContentPage.site !== true || Object.keys(definition.repoContentPage).some((key) => key !== "site"))) {
+    throw new TypeError("repoContentPage must be a boolean or { site: true }");
+  }
+  if (typeof definition.repoContentPage === "object" && !site) {
+    throw new TypeError("repoContentPage.site requires a configured site");
+  }
   return {
     kind: "package.kb",
     ...base,
     navigation: normalizePackageNavigation(definition.navigation),
     ...distribution === undefined ? {} : { distribution },
     assets,
-    ...site === undefined ? {} : { site }
+    ...site === undefined ? {} : { site },
+    ...definition.repoContentPage === undefined ? {} : { repoContentPage: definition.repoContentPage }
   };
 };
 var llmsPackage = (definition) => ({
@@ -32452,6 +32491,11 @@ export {
   resolveEffectiveIndexerComposers,
   requirementSetFromRegistry,
   requirementRef,
+  repoContentScopeMatches,
+  repoContentRegistrySchema,
+  repoContentPathSchema,
+  repoContentMount,
+  repoContentEntrySchema,
   renderIndexerDeterministicFacts,
   relocateUnchangedArticleRegion,
   relevantResults,
@@ -32470,6 +32514,7 @@ export {
   processedScopeSchema,
   processedScopeKey,
   planIndexerPostAuthorComposition,
+  parseRepoContentRef,
   parseLarkSourcesRegistry,
   parseIndexerRegistry,
   parseIndexerProviderManifest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.7.43",
+  "version": "0.7.50",
   "type": "module",
   "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",

package/repoContent.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+export declare const repoContentPathSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const repoContentEntrySchema: z.ZodObject<{
+    kind: z.ZodEnum<["docs", "skills", "document", "skill"]>;
+    path: z.ZodEffects<z.ZodString, string, string>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    group: z.ZodOptional<z.ZodString>;
+    mount: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    kind: "document" | "skill" | "docs" | "skills";
+    title?: string | undefined;
+    description?: string | undefined;
+    exclude?: string[] | undefined;
+    group?: string | undefined;
+    mount?: string | undefined;
+}, {
+    path: string;
+    kind: "document" | "skill" | "docs" | "skills";
+    title?: string | undefined;
+    description?: string | undefined;
+    exclude?: string[] | undefined;
+    group?: string | undefined;
+    mount?: string | undefined;
+}>;
+export declare const repoContentRegistrySchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"context.repo-content/v1">;
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<["docs", "skills", "document", "skill"]>;
+        path: z.ZodEffects<z.ZodString, string, string>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        group: z.ZodOptional<z.ZodString>;
+        mount: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        kind: "document" | "skill" | "docs" | "skills";
+        title?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+        group?: string | undefined;
+        mount?: string | undefined;
+    }, {
+        path: string;
+        kind: "document" | "skill" | "docs" | "skills";
+        title?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+        group?: string | undefined;
+        mount?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    entries: Record<string, {
+        path: string;
+        kind: "document" | "skill" | "docs" | "skills";
+        title?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+        group?: string | undefined;
+        mount?: string | undefined;
+    }>;
+    protocol: "context.repo-content/v1";
+}, {
+    entries: Record<string, {
+        path: string;
+        kind: "document" | "skill" | "docs" | "skills";
+        title?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+        group?: string | undefined;
+        mount?: string | undefined;
+    }>;
+    protocol: "context.repo-content/v1";
+}>;
+export type RepoContentEntry = z.infer<typeof repoContentEntrySchema>;
+export type RepoContentRegistry = z.infer<typeof repoContentRegistrySchema>;
+export declare function repoContentMount(entry: RepoContentEntry): string;
+/** Scope selectors omit a revision; evidence references always include one. */
+export declare function parseRepoContentRef(value: string): {
+    id: string;
+    commit?: string;
+    worktree: boolean;
+} | undefined;
+export declare function repoContentScopeMatches(scope: string, reference: string): boolean;

package/templates/package-templates/kb/skills/knowledge-query/SKILL.md

@@ -25,6 +25,12 @@ as evidence rather than relying on memory or frontmatter summaries.
 
 ## Package Roots
 
+If present, `{{wikisRoot}}/repo-content.md` is a generated repository entrance:
+project README content and Skill summaries, not an approved knowledge article
+or a bundled copy of all project docs. Follow its original links when authorized
+and needed; reading a Skill description does not install or execute it. The
+original repository remains authoritative, and the page states its build baseline.
+
 | Root | Use |
 |---|---|
 | `{{wikisRoot}}/` | Code, business and product reference articles. |

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/SKILL.md

@@ -18,6 +18,10 @@ description: 查询 {{displayName}} 中经过审核、可追溯来源的知识
 
 ## 知识根目录
 
+若存在 `{{wikisRoot}}/repo-content.md`，它是生成的仓库入口页：README 与 Skill
+简介，不是批准知识文章，也不包含全部项目文档。需要且有权访问时沿链接读取原文；
+阅读 Skill 说明不代表安装或执行。原仓库是真源，页面标明构建所用基线。
+
 | 根目录 | 用途 |
 |---|---|
 | `{{wikisRoot}}/` | 来自 codeindex、business、product 的代码、业务和产品说明。 |

package/templates/project-skills/maintain-project-knowledge/SKILL.md

@@ -12,6 +12,13 @@ mappings here.
 
 ## Repository sources
 
+Same-repository docs and authored Skills registered in `repo-content.yaml` are
+not captured source copies. For original edits or registration use
+`context-repo-content`, without starting production. A separately requested
+knowledge update may select `repo-content:<id>`; compare cited document regions
+and entire cited Skill directories, including untracked additions. Inspecting
+or editing never advances the processed baseline. Keep historical real paths.
+
 Start with the current Context Route. If registered repository modules are
 missing or their local links are broken, follow the route-selected repository
 recovery procedure. Let the user choose an existing checkout, authorize a scan

package/templates/project-skills.zh-CN/maintain-project-knowledge/SKILL.md

@@ -11,6 +11,11 @@ Skill，并以当前 Route、资源和命令为权威；这里只保留稳定的
 
 ## 仓库来源的获取和更新
 
+`repo-content.yaml` 登记的同仓文档和自有 Skills 不是采集副本。编辑原文或登记时
+使用 `context-repo-content`，不启动生产。另行授权的知识更新可选择
+`repo-content:<id>`；文档检查引用区域，Skill 检查整个目录及未跟踪新增文件。
+检查与编辑不推进处理基线，旧证据保留当时的真实仓库路径。
+
 先检查当前 Context Route。已登记仓库模块缺失或本地链接断开时，使用 Route
 选择的仓库恢复流程，让用户选择已有 checkout、授权在一个限定目录内扫描，
 或明确允许 clone 已登记的固定 commit。