@c4a/context 0.7.43 → 0.7.55

package/docs/README.md

@@ -22,6 +22,7 @@ preload the whole manual set.
 
 | Current need | Read |
 |---|---|
+| Associate external knowledge, Skills or plugins without copying them | [External associations](./guides/imports.md) |
 | Customize website pages, homepage slots or a floating chat widget | [Page Content Customization](./guides/page-customization.md) |
 | Understand the whole knowledge-project shape | [Getting Started](./getting-started.md) |
 | Know what the Agent may decide or change | [Agent Guide](./guides/agent-guide.md) and [Agent Dialogue](./guides/agent-dialogue.md) |

package/docs/README.zh-CN.md

@@ -13,6 +13,7 @@
 
 | 当前需要 | 阅读内容 |
 |---|---|
+| 关联外部知识、Skill 或插件，不复制内容 | [外部关联](./guides/imports.md) |
 | 理解完整知识项目的形态 | [Getting Started](./getting-started.md) |
 | 判断 Agent 可以决定或修改什么 | [Agent Guide](./guides/agent-guide.md) 和 [Agent Dialogue](./guides/agent-dialogue.md) |
 | 配置来源、采集、Indexer 或产物 | [Project API](./reference/project-api.md) |

package/docs/guides/imports.md

@@ -0,0 +1,84 @@
+# External associations
+
+Workspace-root `imports.yaml` declares external entrances without downloading,
+installing or capturing their contents. Maintain it through the Context entry when
+the task requests a lasting association. Temporary query reads do not register
+dependencies. Same-repository authored documents and Skills use
+[repo-content](repo-content.md) instead.
+
+```yaml
+protocol: context.imports/v1
+imports:
+  engineering-guide:
+    kind: knowledge
+    url: https://docs.example.org/engineering/
+    description: Engineering conventions
+  release-check:
+    kind: skill
+    url: https://github.com/example/skills/tree/v1/skills/release-check
+    path: skills/release-check
+    version: v1
+```
+
+The stable ID and `url` are required. `kind`, `format`, `title`, `description`,
+`path` and `version` are optional. Kind and format are open strings; versions are
+opaque hints, not necessarily SemVer. Paths are source-relative without traversal.
+Reader URLs must be HTTP(S), without credentials or whitespace; this is local
+syntax validation, not a provider whitelist or availability check. Do not put
+access tokens in query strings. The SDK exports `importsRegistrySchema` for local
+validation. Unknown providers and offline operation do not cause network checks.
+
+Use a new ID when replacing the source identity. A declaration is neither proof
+of reading nor an installation record. Do not expand transitive imports or infer
+permission from a readable service. Only relevant originals are read through
+existing host tools. Installed capability identity belongs to the host, not a
+Context lock file.
+
+## Entrances and evidence
+
+An import is a reader entrance, not recorded evidence. It adds no entry to
+`knowledge/structure.yaml` `references[]`, produces no review hint and has no
+`import:` reference format. When an article's conclusion must be traceable or
+tracked for change, register the needed external content as a source and capture
+it; the import can remain as the reader entrance.
+
+The CLI never contacts providers or compares versions. When asked to update or
+check imports, the Agent observes current versions with existing authorized host
+tools and compares them with `version`. Unreachable, unauthorized or failed checks
+are reported as "version unknown" and are never treated as a change.
+
+## Links and output
+
+`[Engineering guide](context:import/engineering-guide)` in an article projects to
+the declared URL. Build never guesses a provider-specific URL, appends `path` or
+rewrites the version. Use an entrance that already opens the intended target.
+Missing IDs keep the reader label as non-clickable text and produce a build link
+warning. An invalid or unreadable declaration skips the optional directory and
+degrades affected links the same way; unrelated outputs still build. Correct
+`imports.yaml` or the article link to restore navigation. Merely registering
+entries emits no page.
+
+For an optional declaration-only directory:
+
+```ts
+kbPackage({
+  name: "handbook",
+  template: { path: "src/package-templates/kb" },
+  importsPage: true,
+})
+```
+
+This generates `wikis/imports.md` and includes it in package navigation. With an
+existing `site` configuration, `importsPage: { site: true }` also adds a website
+navigation item. `false` or omission disables generation. Initialization enables
+the package directory when a valid `imports.yaml` already exists. An invalid
+declaration is preserved with a warning; initialization continues without enabling
+that directory. When first configuring
+a new workspace's KB later, enable it if the declaration is present; preserve
+existing settings and explicit user choices. The directory contains only declared metadata,
+not approved article bodies or installation commands. Check audience suitability
+before exposing private entrances.
+
+Navigation links are not source evidence. Imports declaration support alone does
+not authorize fabricated `import:` fragment references or advancement of article
+evidence baselines.

package/docs/guides/knowledge-updates.md

@@ -18,6 +18,30 @@ 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.
+
+External associations in `imports.yaml` are entrances, not recorded evidence:
+they create no `references[]` and no review hints, and the CLI never checks
+their versions. When the user asks to update or check external associations,
+use existing authorized Host tools (for example `git ls-remote`, a package
+manager or a web read) to observe each selected entry's current version and
+compare it with its optional `version`. If it differs, read only what the
+linked articles rely on, report whether they need revision and update
+`version` once settled. Unreachable, unauthorized or failed checks are
+"version unknown": report them, keep `version` unchanged, and never treat them
+as changed. When an article's conclusion must trace or track external content,
+register the needed part as a source and capture it; do not cite the
+association itself as evidence.
+
 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,19 @@ 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.
+
+External associations have an optional [directory](imports.md): `importsPage: true`
+generates `wikis/imports.md` from declarations only; `{ site: true }` also exposes
+it on a configured website. Neither option downloads or installs external content.
+
+When first declaring a KB for a new workspace, enable `repoContentPage: true`
+if `repo-content.yaml` exists and `importsPage: true` if `imports.yaml` exists.
+Keep existing package settings and explicit user choices; website exposure stays opt-in.
+
 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/imports.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+/** Validate a portable reader entrance, never contact its provider. */
+export declare const importUrlSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const importIdSchema: z.ZodString;
+export declare const importEntrySchema: z.ZodObject<{
+    url: z.ZodEffects<z.ZodString, string, string>;
+    kind: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    version: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    path?: string | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+    kind?: string | undefined;
+    version?: string | undefined;
+    format?: string | undefined;
+}, {
+    url: string;
+    path?: string | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+    kind?: string | undefined;
+    version?: string | undefined;
+    format?: string | undefined;
+}>;
+export declare const importsRegistrySchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"context.imports/v1">;
+    imports: z.ZodRecord<z.ZodString, z.ZodObject<{
+        url: z.ZodEffects<z.ZodString, string, string>;
+        kind: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        version: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        url: string;
+        path?: string | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        kind?: string | undefined;
+        version?: string | undefined;
+        format?: string | undefined;
+    }, {
+        url: string;
+        path?: string | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        kind?: string | undefined;
+        version?: string | undefined;
+        format?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    protocol: "context.imports/v1";
+    imports: Record<string, {
+        url: string;
+        path?: string | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        kind?: string | undefined;
+        version?: string | undefined;
+        format?: string | undefined;
+    }>;
+}, {
+    protocol: "context.imports/v1";
+    imports: Record<string, {
+        url: string;
+        path?: string | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        kind?: string | undefined;
+        version?: string | undefined;
+        format?: string | undefined;
+    }>;
+}>;
+export type ImportEntry = z.infer<typeof importEntrySchema>;
+export type ImportsRegistry = z.infer<typeof importsRegistrySchema>;

package/index.d.ts

@@ -5,6 +5,8 @@ import type { PackageNavigationDefinition, PackageSelectDefinition } from "./con
 import type { PhaseDefinition, PhaseResourceReference } from "./phases.js";
 import type { ProjectSourceDefinition } from "./sources.js";
 export * from "./indexerCoreExports.js";
+export { importsRegistrySchema, importEntrySchema, importUrlSchema, importIdSchema, type ImportEntry, type ImportsRegistry } from "./imports.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 +111,12 @@ export type KbPackageDefinition = BasePackageDefinition & {
     distribution?: PackageDistributionDefinition;
     assets?: PackageAssetDefinition;
     site?: PackageSiteDefinition;
+    repoContentPage?: boolean | {
+        site: true;
+    };
+    importsPage?: boolean | {
+        site: true;
+    };
 };
 export type LlmsPackageDefinition = BasePackageDefinition & {
     kind: "package.llms";
@@ -132,6 +140,12 @@ export declare const kbPackage: (definition: {
     distribution?: PackageDistributionDefinition;
     assets?: PackageAssetDefinition;
     site?: PackageSiteDefinition;
+    repoContentPage?: boolean | {
+        site: true;
+    };
+    importsPage?: boolean | {
+        site: true;
+    };
 }) => KbPackageDefinition;
 export declare const llmsPackage: (definition: {
     name: string;

package/index.js

@@ -22134,6 +22134,64 @@ 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/imports.ts
+var importUrlSchema = exports_external.string().min(1).refine((value) => {
+  if (!/^https?:\/\/[^/?#\\]/iu.test(value) || /[\s\u0000-\u001f\u007f<>\\]/u.test(value))
+    return false;
+  try {
+    const url = new URL(value);
+    return ["https:", "http:"].includes(url.protocol) && !!url.hostname && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}, "Use an absolute http:// or https:// entrance without credentials, whitespace or backslashes");
+var importIdSchema = exports_external.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u);
+var importEntrySchema = exports_external.object({
+  url: importUrlSchema,
+  kind: exports_external.string().min(1).optional(),
+  format: exports_external.string().min(1).optional(),
+  title: exports_external.string().min(1).optional(),
+  description: exports_external.string().optional(),
+  path: repoContentPathSchema.optional(),
+  version: exports_external.string().min(1).optional()
+}).strict();
+var importsRegistrySchema = exports_external.object({
+  protocol: exports_external.literal("context.imports/v1"),
+  imports: exports_external.record(importIdSchema, importEntrySchema)
+}).strict();
 // src/indexerRequirementComparison.ts
 function setRelation(oldValues, newValues) {
   const oldContained = [...oldValues].every((value) => newValues.has(value));
@@ -32170,7 +32228,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 +32296,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 +32332,27 @@ var kbPackage = (definition) => {
   const distribution = normalizePackageDistribution(definition.distribution);
   const assets = normalizePackageAssets(definition.assets);
   const site = normalizePackageSite(definition.site);
+  if (definition.importsPage !== undefined && typeof definition.importsPage !== "boolean" && (!definition.importsPage || typeof definition.importsPage !== "object" || definition.importsPage.site !== true || Object.keys(definition.importsPage).some((key) => key !== "site"))) {
+    throw new TypeError("importsPage must be a boolean or { site: true }");
+  }
+  if (typeof definition.importsPage === "object" && !site) {
+    throw new TypeError("importsPage.site requires a configured 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 },
+    ...definition.importsPage === undefined ? {} : { importsPage: definition.importsPage }
   };
 };
 var llmsPackage = (definition) => ({
@@ -32452,6 +32524,11 @@ export {
   resolveEffectiveIndexerComposers,
   requirementSetFromRegistry,
   requirementRef,
+  repoContentScopeMatches,
+  repoContentRegistrySchema,
+  repoContentPathSchema,
+  repoContentMount,
+  repoContentEntrySchema,
   renderIndexerDeterministicFacts,
   relocateUnchangedArticleRegion,
   relevantResults,
@@ -32470,6 +32547,7 @@ export {
   processedScopeSchema,
   processedScopeKey,
   planIndexerPostAuthorComposition,
+  parseRepoContentRef,
   parseLarkSourcesRegistry,
   parseIndexerRegistry,
   parseIndexerProviderManifest,
@@ -32816,6 +32894,10 @@ export {
   indexerActivationRequestSchema,
   indexRequirementSetSchema,
   indexRequirementSchema,
+  importsRegistrySchema,
+  importUrlSchema,
+  importIdSchema,
+  importEntrySchema,
   failIndexerPostAuthorRun,
   failIndexerMainRun,
   expectedProviderResolutionFromAction,