@c4a/context 0.6.0-beta.8 → 0.6.1-beta.2

package/index.js

@@ -6916,6 +6916,10 @@ var require_public_api = __commonJS((exports) => {
 });
 
 // src/contracts.ts
+var DEFAULT_PACKAGE_NAVIGATION = {
+  foldDirectoryIndexes: true,
+  maxInlineEntries: 50
+};
 var DOC_MAINLINE_COLLECTIONS = [
   "business",
   "product",
@@ -11768,8 +11772,22 @@ function assertUniquePhaseIds(phases) {
     firstById.set(phase.id, { index, kind: phase.kind });
   }
 }
+function assertUniquePackageKnowledgeNamespaces(packages) {
+  const firstByNamespace = new Map;
+  for (const [index, pkg] of packages.entries()) {
+    const namespace = pkg.kind === "package.kb" ? pkg.distribution?.knowledgeNamespace : undefined;
+    if (namespace === undefined)
+      continue;
+    const first = firstByNamespace.get(namespace);
+    if (first !== undefined) {
+      throw new TypeError(`Duplicate package knowledge namespace ${JSON.stringify(namespace)}: packages[${first.index}] (${first.name}) conflicts with packages[${index}] (${pkg.name}). Every distributable knowledge package namespace must be unique.`);
+    }
+    firstByNamespace.set(namespace, { index, name: pkg.name });
+  }
+}
 var defineProject = (project) => {
   assertUniquePhaseIds(project.phases);
+  assertUniquePackageKnowledgeNamespaces(project.packages);
   return {
     kind: "context.project",
     project
@@ -11818,7 +11836,20 @@ var normalizeSelect = (select) => {
   }
   return Object.keys(normalized).length > 0 ? normalized : undefined;
 };
+var normalizePackageNavigation = (navigation) => {
+  const maxInlineEntries = navigation?.maxInlineEntries ?? DEFAULT_PACKAGE_NAVIGATION.maxInlineEntries;
+  if (!Number.isSafeInteger(maxInlineEntries) || maxInlineEntries < 1) {
+    throw new TypeError(`Package navigation.maxInlineEntries must be a positive safe integer: ${maxInlineEntries}`);
+  }
+  return {
+    foldDirectoryIndexes: navigation?.foldDirectoryIndexes ?? DEFAULT_PACKAGE_NAVIGATION.foldDirectoryIndexes,
+    maxInlineEntries
+  };
+};
 var PACKAGE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+var PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+var PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_MAX_LENGTH = 48;
+var PACKAGE_KNOWLEDGE_NAMESPACE_MAX_LENGTH = 128;
 var isSafeProjectRelativePath = (value) => {
   if (value.length === 0)
     return false;
@@ -11838,6 +11869,19 @@ var assertSelectCollections = (collections) => {
     assertKnowledgeCollection(collection, "Package select.collections");
   }
 };
+var normalizePackageDistribution = (distribution) => {
+  if (distribution === undefined)
+    return;
+  if (typeof distribution.knowledgeNamespace !== "string") {
+    throw new TypeError("Package distribution.knowledgeNamespace must be a string.");
+  }
+  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))) {
+    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 };
+};
 var assertSelectOkfRoots = (roots) => {
   for (const root of roots) {
     assertOkfRoot(root, "Package select.okfRoots");
@@ -11880,10 +11924,19 @@ var createPackageDefinitionBase = (kind, definition) => {
   }
   return packageDefinition;
 };
-var kbPackage = (definition) => ({
-  kind: "package.kb",
-  ...createPackageDefinitionBase("kb", definition)
-});
+var kbPackage = (definition) => {
+  const base = createPackageDefinitionBase("kb", definition);
+  const distribution = normalizePackageDistribution(definition.distribution ?? { knowledgeNamespace: definition.name });
+  if (distribution === undefined) {
+    throw new TypeError("KB package distribution must resolve to a knowledge namespace.");
+  }
+  return {
+    kind: "package.kb",
+    ...base,
+    navigation: normalizePackageNavigation(definition.navigation),
+    distribution
+  };
+};
 var llmsPackage = (definition) => ({
   kind: "package.llms",
   ...createPackageDefinitionBase("llms", definition)
@@ -11922,6 +11975,7 @@ export {
   DOCUMENT_EVIDENCE_SECTION_VALIDATION_STAGES,
   DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION,
   DEFAULT_REPO_SOURCES_REGISTRY_PATH,
+  DEFAULT_PACKAGE_NAVIGATION,
   DEFAULT_LARK_SOURCES_REGISTRY_PATH,
   DEFAULT_FILE_SOURCES_REGISTRY_PATH
 };

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.0-beta.8",
+  "version": "0.6.1-beta.2",
   "type": "module",
+  "description": "Context SDK — project-local configuration and workspace primitives",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/context4ai/context.git",
+    "directory": "packages/context"
+  },
+  "keywords": [
+    "context",
+    "sdk",
+    "knowledge",
+    "workspace"
+  ],
   "dependencies": {
     "yaml": "^2.5.1",
     "zod": "^3.23.8"

package/templates/package-templates/kb/AGENTS.md

@@ -11,20 +11,20 @@ Approved knowledge files: `{{knowledgeCount}}`
 Use the Markdown files in this package as source-linked product and code
 knowledge. Prefer cited facts from the included knowledge pages over memory.
 
-The `skills/knowledge-query/SKILL.md` entry teaches agents how to navigate OKF
-indexes and cite copied OKF root directories, starting with
-`wikis/`. Customize template files before build when the package needs
+The bundled knowledge-query Skill teaches agents how to navigate OKF indexes
+and cite copied OKF root directories, starting with
+`{{wikisRoot}}/`. Customize template files before build when the package needs
 product-specific skills or routing rules.
 
-Selected OKF root directories such as `wikis/`, `guides/`, `rules/`, and
-`feats/` follow the C4A OKF Profile: OKF fields and C4A extension fields stay
+Selected OKF root directories such as `{{wikisRoot}}/`, `{{guidesRoot}}/`,
+`{{rulesRoot}}/`, and `{{featsRoot}}/` follow the C4A OKF Profile: OKF fields and C4A extension fields stay
 at the top level, and no `context` or `schema` field is emitted. Root mapping:
-`wikis/` maps from structured `codegraph`, `business`, and `product` knowledge;
-`guides/` maps from `architecture`, `sop`, `faq`, `decision`, and `incident`;
-`rules/` maps from `standards` and `test`; `feats/` maps from `feats`. Treat
-`wikis/` as the entity-and-relationship layer; guides and rules may explain or
+`{{wikisRoot}}/` maps from structured `codegraph`, `business`, and `product` knowledge;
+`{{guidesRoot}}/` maps from `architecture`, `sop`, `faq`, `decision`, and `incident`;
+`{{rulesRoot}}/` maps from `standards` and `test`; `{{featsRoot}}/` maps from `feats`. Treat
+`{{wikisRoot}}/` as the entity-and-relationship layer; guides and rules may explain or
 constrain that layer. Customize
-`wikis/index.md` before build to describe the package scope and query guidance;
+the logical `wikis/index.md` template before build to describe the package scope and query guidance;
 other selected OKF root indexes are generated unless this template supplies
 them.
 

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

@@ -1,5 +1,5 @@
 ---
-name: knowledge-query
+name: {{skillName}}
 description: Query the approved knowledge bundled with {{displayName}}.
 ---
 
@@ -48,10 +48,10 @@ beyond the packaged content.
 
 | User intent | First move | Evidence move |
 |---|---|---|
-| Vague topic or unknown name | Open the package's OKF root index, usually `wikis/index.md`, then child indexes such as `wikis/<group>/index.md`. If the package includes other selected OKF roots such as `guides/` or `rules/`, use their indexes too. | Choose candidate pages by title, path, frontmatter, and index grouping. |
-| Architecture, procedure, FAQ, decision, incident, or troubleshooting question | Start from `guides/index.md` when present. These pages are mapped from internal `architecture`, `sop`, `faq`, `decision`, and `incident` collections. | Use guide pages for explanations, design narratives, decisions, steps, operational context, and troubleshooting; cite the relevant sections. |
-| Structured product or business question | Start from `wikis/index.md`, then the `product` or `business` group index. | Use entity pages and typed relationships to establish scope before reading supporting narratives. |
-| Standard, constraint, acceptance, or test scenario question | Start from `rules/index.md` when present. These pages are mapped from internal `standards` and `test` collections. | Use rule pages for normative constraints, acceptance criteria, and validation scenarios. |
+| Vague topic or unknown name | Open the package's OKF root index, usually `{{wikisRoot}}/index.md`, then its child indexes. If the package includes other selected OKF roots such as `{{guidesRoot}}/` or `{{rulesRoot}}/`, use their indexes too. | Choose candidate pages by title, path, frontmatter, and index grouping. |
+| Architecture, procedure, FAQ, decision, incident, or troubleshooting question | Start from `{{guidesRoot}}/index.md` when present. These pages are mapped from internal `architecture`, `sop`, `faq`, `decision`, and `incident` collections. | Use guide pages for explanations, design narratives, decisions, steps, operational context, and troubleshooting; cite the relevant sections. |
+| Structured product or business question | Start from `{{wikisRoot}}/index.md`, then the `product` or `business` group index. | Use entity pages and typed relationships to establish scope before reading supporting narratives. |
+| Standard, constraint, acceptance, or test scenario question | Start from `{{rulesRoot}}/index.md` when present. These pages are mapped from internal `standards` and `test` collections. | Use rule pages for normative constraints, acceptance criteria, and validation scenarios. |
 | Specific entity/domain/action named | Open the matching page or nearest group index. | Read the page sections and source metadata. |
 | Relationship or impact question | Check `context-build-inventory.json` `structure.edge_records`, then related endpoint pages. | Cite typed edge evidence if available; otherwise cite page sections and mark relation gaps. |
 | Detail within a known page | Read that page's relevant `context:section` block. | Cite the section id/source_ref and quote or summarize only supported text. |
@@ -79,11 +79,11 @@ matches.
 
 ## Workflow
 
-1. Start with the relevant OKF root index, usually `wikis/index.md`, to
+1. Start with the relevant OKF root index, usually `{{wikisRoot}}/index.md`, to
    understand the package scope.
-2. Follow OKF directory indexes such as `wikis/<group>/index.md` before opening
-   pages. If the package includes other selected OKF roots, inspect their
-   indexes the same way.
+2. Follow the links exposed by that index. Small directories may link directly
+   to pages; larger directories may expose their own `index.md`. If the package
+   includes other selected OKF roots, inspect their root indexes the same way.
 3. Open only the candidate pages needed for the question; avoid workspace-wide
    reading unless the user asks for an inventory.
 4. Inspect frontmatter `node_type`, `sources`, and `context:section` comments to
@@ -184,13 +184,14 @@ the user it is false; distinguish "not evidenced here" from "not true."
 
 ## Knowledge Boundary
 
-- The bundled OKF root directories, usually including `wikis/`, are the source
+- The bundled OKF root directories, usually including `{{wikisRoot}}/`, are the source
   of truth for this skill.
-- OKF root mapping: `wikis/` maps from the structured `codegraph`, `business`,
-  and `product` collections; `guides/` maps from `architecture`, `sop`, `faq`,
-  `decision`, and `incident`; `rules/` maps from `standards` and `test`;
-  `feats/` maps from `feats`.
-- Treat `wikis/` as the primary entity-and-relationship layer. Guides and rules
+- OKF root mapping: `{{wikisRoot}}/` maps from the structured `codegraph`,
+  `business`, and `product` collections; `{{guidesRoot}}/` maps from
+  `architecture`, `sop`, `faq`, `decision`, and `incident`;
+  `{{rulesRoot}}/` maps from `standards` and `test`; `{{featsRoot}}/` maps from
+  `feats`.
+- Treat `{{wikisRoot}}/` as the primary entity-and-relationship layer. Guides and rules
   may explain, operationalize, or constrain that structured knowledge, but
   directory co-location alone is not relationship evidence.
 - Bundled OKF root directories follow the C4A OKF Profile.

package/templates/package-templates/kb/wikis/index.md

@@ -6,7 +6,7 @@ tags:
   - context
   - knowledge-base
 timestamp: "{{knowledgeTimestamp}}"
-resource: "context://package/{{packageName}}/wikis"
+resource: "context://package/{{packageName}}/{{wikisRoot}}"
 package: "{{packageName}}"
 package_kind: "{{packageKind}}"
 knowledge_count: {{knowledgeCount}}
@@ -14,7 +14,7 @@ knowledge_count: {{knowledgeCount}}
 
 <!-- context:template
 This file is a starter template. It is rendered by `context build` and copied to
-`dist/<package-name>/wikis/index.md`.
+`dist/<package-name>/{{wikisRoot}}/index.md`.
 
 Template comments that start with `context:template` are removed from build output.
 Read the template variable guide before customizing:
@@ -22,9 +22,9 @@ node_modules/@c4a/context/docs/reference/template-variables.md
 
 Customize this file before calling the package usable. Add the bundle scope,
 intended readers, recommended reading order, known gaps, product scenarios,
-or task-focused entry sections. The default root index lists only the
-next-level directories; context build generates directory-level index.md
-files below it.
+or task-focused entry sections. The default root index links small directory
+contents directly and links to child index.md files when a directory exceeds
+the package navigation threshold.
 -->
 
 # {{displayName}}
@@ -38,6 +38,6 @@ Use this index as the entry point, then open the linked knowledge pages for sour
 
 ## How To Use
 
-- Start from the directory list above, then open child indexes and linked knowledge pages for source-linked details.
-- Use `skills/knowledge-query/SKILL.md` when this bundle is installed as an agent knowledge package.
+- Start from the navigation above, then open linked pages or child indexes for source-linked details.
+- Use the bundled knowledge-query Skill when this bundle is installed as an agent knowledge package.
 - Customize `src/package-templates/kb/wikis/index.md` before build to add bundle scope, known gaps, project-specific reading paths, or task entry points.