ctxr-cli 0.1.0

package/dist/config/schema.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+/**
+ * store-lifecycle spec: schema_version versions STORE STATE (config shape +
+ * note frontmatter conventions) — a monotonic integer independent of the npm
+ * package version — not "what this CLI release happens to be."
+ */
+/**
+ * Bumped to 2 by the visibility-field key rename migration (store-lifecycle
+ * spec task 9.2) — proof that renaming DEFAULT_VISIBILITY_FIELD_KEY really
+ * is "a config-default change plus a migration, never a spec or code
+ * rewrite" (design.md D7): every consumer already reads
+ * config.fields.visibility, never a literal key, so nothing else changed.
+ */
+export declare const SUPPORTED_SCHEMA_VERSION = 2;
+export declare const TaxonomyLayerSchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
+/**
+ * disclosure-policy spec: "v1 keeps the disclosure ladder's shape with a
+ * flat, user-defined value list" (design.md) — no registry syntax, just a
+ * flat set of audience names the operator considers internal, and a flat
+ * list of hard-wall rules evaluated before any tag or visibility rung.
+ */
+declare const HardWallSchema: z.ZodObject<{
+    audience: z.ZodString;
+    note_path_prefix: z.ZodOptional<z.ZodString>;
+    except: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    verdict: z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        deny: "deny";
+    }>;
+}, z.core.$strip>;
+declare const AdapterDeclarationSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        forge: "forge";
+        "harness-generation": "harness-generation";
+        "identity-injection": "identity-injection";
+    }>;
+    module: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const StoreConfigSchema: z.ZodObject<{
+    schema_version: z.ZodNumber;
+    taxonomy: z.ZodObject<{
+        profile: z.ZodString;
+        layers: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            path: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    fields: z.ZodObject<{
+        visibility: z.ZodString;
+    }, z.core.$loose>;
+    visibility: z.ZodObject<{
+        default_context: z.ZodString;
+        directory_defaults: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        contexts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>;
+    derived: z.ZodObject<{
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    retrieval: z.ZodObject<{
+        exclude_paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    git: z.ZodObject<{
+        default_branch: z.ZodString;
+    }, z.core.$strip>;
+    session: z.ZodObject<{
+        branch_prefix: z.ZodString;
+        worktrees_path: z.ZodString;
+    }, z.core.$strip>;
+    write_lifecycle: z.ZodObject<{
+        diff_size_ceiling_lines: z.ZodNumber;
+    }, z.core.$strip>;
+    catalog: z.ZodObject<{
+        path: z.ZodString;
+        section_max_bytes: z.ZodNumber;
+    }, z.core.$strip>;
+    disclosure: z.ZodObject<{
+        internal_audiences: z.ZodArray<z.ZodString>;
+        hard_walls: z.ZodArray<z.ZodObject<{
+            audience: z.ZodString;
+            note_path_prefix: z.ZodOptional<z.ZodString>;
+            except: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            verdict: z.ZodEnum<{
+                allow: "allow";
+                ask: "ask";
+                deny: "deny";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    ingest: z.ZodObject<{
+        inbox_path: z.ZodString;
+    }, z.core.$strip>;
+    organize: z.ZodObject<{
+        archive_path: z.ZodString;
+    }, z.core.$strip>;
+    identity: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>;
+    harness: z.ZodObject<{
+        procedures_path: z.ZodString;
+        conventions_path: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    adapters: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            forge: "forge";
+            "harness-generation": "harness-generation";
+            "identity-injection": "identity-injection";
+        }>;
+        module: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type StoreConfig = z.infer<typeof StoreConfigSchema>;
+export type TaxonomyLayerConfig = z.infer<typeof TaxonomyLayerSchema>;
+export type HardWallConfig = z.infer<typeof HardWallSchema>;
+export type AdapterDeclaration = z.infer<typeof AdapterDeclarationSchema>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AAiEH;;;;;GAKG;AACH,QAAA,MAAM,cAAc;;;;;;;;;iBAQlB,CAAC;AAoCH,QAAA,MAAM,wBAAwB;;;;;;;;iBAI5B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmBd,CAAC;AAEjB,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC5D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/config/schema.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+/**
+ * store-lifecycle spec: schema_version versions STORE STATE (config shape +
+ * note frontmatter conventions) — a monotonic integer independent of the npm
+ * package version — not "what this CLI release happens to be."
+ */
+/**
+ * Bumped to 2 by the visibility-field key rename migration (store-lifecycle
+ * spec task 9.2) — proof that renaming DEFAULT_VISIBILITY_FIELD_KEY really
+ * is "a config-default change plus a migration, never a spec or code
+ * rewrite" (design.md D7): every consumer already reads
+ * config.fields.visibility, never a literal key, so nothing else changed.
+ */
+export const SUPPORTED_SCHEMA_VERSION = 2;
+export const TaxonomyLayerSchema = z.object({
+    name: z.string().min(1),
+    path: z.string().min(1),
+    description: z.string().min(1),
+});
+const TaxonomySchema = z.object({
+    /** A shipped profile id, or "custom" when a custom taxonomy definition was supplied. */
+    profile: z.string().min(1),
+    layers: z.array(TaxonomyLayerSchema),
+});
+/**
+ * Loose (passthrough), not strict: a later phase adding its own field key
+ * (e.g. audience tagging) must not force every existing store through a
+ * migration just to keep loading. schema_version bumps only on a genuinely
+ * incompatible change, never on an additive one.
+ */
+const FieldsSchema = z
+    .object({
+    visibility: z.string().min(1),
+})
+    .passthrough();
+const VisibilitySchema = z.object({
+    default_context: z.string().min(1),
+    directory_defaults: z.record(z.string(), z.string()).default({}),
+    /**
+     * context-visibility spec (visibility-contexts-and-wall-verdicts): which
+     * visibility VALUES each named context can see. A context with no entry
+     * sees exactly its own value (identity default) — so an unconfigured
+     * store behaves byte-identically to the equality matching this replaced,
+     * and an unknown context fails closed to that same identity match.
+     */
+    contexts: z.record(z.string(), z.array(z.string())).default({}),
+});
+const DerivedSchema = z.object({
+    paths: z.array(z.string()),
+});
+const RetrievalSchema = z.object({
+    exclude_paths: z.array(z.string()),
+});
+/**
+ * Recorded once, at init, from whatever branch `git init` actually created
+ * (never hardcoded to "main") — this is what lets the pre-push hook refuse
+ * a push to the default branch without re-deriving it from a possibly
+ * network-dependent `git remote show` at hook time.
+ */
+const GitSchema = z.object({
+    default_branch: z.string().min(1),
+});
+const SessionSchema = z.object({
+    branch_prefix: z.string().min(1),
+    worktrees_path: z.string().min(1),
+});
+const WriteLifecycleSchema = z.object({
+    diff_size_ceiling_lines: z.number().int().positive(),
+});
+const CatalogSchema = z.object({
+    path: z.string().min(1),
+    section_max_bytes: z.number().int().positive(),
+});
+/**
+ * disclosure-policy spec: "v1 keeps the disclosure ladder's shape with a
+ * flat, user-defined value list" (design.md) — no registry syntax, just a
+ * flat set of audience names the operator considers internal, and a flat
+ * list of hard-wall rules evaluated before any tag or visibility rung.
+ */
+const HardWallSchema = z.object({
+    /** A named audience, or "*" to match every audience. */
+    audience: z.string().min(1),
+    /** Omitted means the wall applies to every note. */
+    note_path_prefix: z.string().min(1).optional(),
+    /** Audiences this wall does NOT apply to — evaluation falls through to later rungs for them. */
+    except: z.array(z.string()).optional(),
+    verdict: z.enum(['allow', 'deny', 'ask']),
+});
+const DisclosureSchema = z.object({
+    internal_audiences: z.array(z.string()),
+    hard_walls: z.array(HardWallSchema),
+});
+/** context-ingest spec: where capture lands raw material before ingest stamps identity onto it. */
+const IngestSchema = z.object({
+    inbox_path: z.string().min(1),
+});
+/** context-organize spec: archive's destination — independent of taxonomy layers, so it works under any profile. */
+const OrganizeSchema = z.object({
+    archive_path: z.string().min(1),
+});
+/** agent-identity spec: canonical identity files live here, excluded from every retrieval leg. */
+const IdentitySchema = z.object({
+    path: z.string().min(1),
+});
+/** harness-portability spec: the portable procedure pack and operator convention docs AGENTS.md's indexes point into. */
+const HarnessSchema = z.object({
+    procedures_path: z.string().min(1),
+    conventions_path: z.string().min(1).default('.contexture/conventions/'),
+});
+/**
+ * adapters spec: the one declared-registration mechanism shared by every
+ * adapter kind. `module` is reserved for a future third-party-loading path;
+ * v1 resolves every entry against the built-in adapter registry by
+ * (kind, id).
+ */
+const AdapterKindSchema = z.enum(['harness-generation', 'identity-injection', 'forge']);
+const AdapterDeclarationSchema = z.object({
+    id: z.string().min(1),
+    kind: AdapterKindSchema,
+    module: z.string().min(1).optional(),
+});
+export const StoreConfigSchema = z
+    .object({
+    schema_version: z.number().int().positive(),
+    taxonomy: TaxonomySchema,
+    fields: FieldsSchema,
+    visibility: VisibilitySchema,
+    derived: DerivedSchema,
+    retrieval: RetrievalSchema,
+    git: GitSchema,
+    session: SessionSchema,
+    write_lifecycle: WriteLifecycleSchema,
+    catalog: CatalogSchema,
+    disclosure: DisclosureSchema,
+    ingest: IngestSchema,
+    organize: OrganizeSchema,
+    identity: IdentitySchema,
+    harness: HarnessSchema,
+    adapters: z.array(AdapterDeclarationSchema),
+})
+    .passthrough();
+//# sourceMappingURL=schema.js.map

package/dist/config/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}

package/dist/core/agents-doc.d.ts

@@ -0,0 +1,80 @@
+import type { StoreConfig } from '../config/schema.js';
+import { type ScannedDoc } from './conventions.js';
+/**
+ * context-retrieval spec (task 4.5): the leg-routing rule that tells an
+ * agent which of its two retrieval legs to use for a given question — the
+ * catalog/graph (contexture-built-and-maintained) or its own direct content
+ * matching (grep, scoped by the store's declared exclusion paths). This is
+ * one fenced region within AGENTS.md; Phase 8 adds the canonical template's
+ * other sections (root-resolution, frontmatter schema, write-path, procedure
+ * index) as sibling regions in the same file, never touching this one.
+ */
+export declare const AGENTS_MD_LEG_ROUTING_FENCE: import("./markers.js").Fence;
+export declare function agentsMdPath(root: string): string;
+export declare function renderLegRoutingSection(config: StoreConfig): string[];
+/** Idempotently reconciles AGENTS.md's leg-routing section from current config — called at init and on re-init. */
+export declare function buildAgentsLegRoutingSection(root: string, config: StoreConfig): Promise<{
+    changed: boolean;
+}>;
+/**
+ * context-ingest spec (task 6.3): capture is a plain file write an agent
+ * does directly with its own tools — no CLI command wraps it, the same
+ * "agents gather, the CLI computes/writes/verifies" split that dropped
+ * `ctxr search`. This section documents the one rule that write must
+ * follow, so it isn't only tribal knowledge: no source-identity fields, and
+ * where the file goes.
+ */
+export declare const AGENTS_MD_CAPTURE_FENCE: import("./markers.js").Fence;
+export declare function renderCaptureSection(config: StoreConfig): string[];
+export declare function buildAgentsCaptureSection(root: string, config: StoreConfig): Promise<{
+    changed: boolean;
+}>;
+/**
+ * context-organize spec (task 7.1): the placement procedure is
+ * documentation driven entirely by the configured taxonomy, never a
+ * hardcoded layout — this section is generated purely from
+ * `config.taxonomy.layers`, so it reads correctly under PARA, Zettelkasten,
+ * Diátaxis, or any custom taxonomy without a single layer name appearing in
+ * this file's own source.
+ */
+export declare const AGENTS_MD_PLACEMENT_FENCE: import("./markers.js").Fence;
+export declare function renderPlacementSection(config: StoreConfig): string[];
+export declare function buildAgentsPlacementSection(root: string, config: StoreConfig): Promise<{
+    changed: boolean;
+}>;
+/**
+ * harness-portability spec (task 8.5): the canonical template's four
+ * required pieces — root-resolution rule, frontmatter schema pointer,
+ * write-path rule, and a procedure index — so an agent that has read only
+ * this file, with no harness-specific context, has everything it needs
+ * (the spec's own "Reading only AGENTS.md is sufficient" scenario).
+ */
+export declare const AGENTS_MD_CANONICAL_FENCE: import("./markers.js").Fence;
+export declare function renderCanonicalSection(config: StoreConfig, procedures: readonly ScannedDoc[]): string[];
+export declare function buildAgentsCanonicalSection(root: string, config: StoreConfig): Promise<{
+    changed: boolean;
+}>;
+/**
+ * entry-doc-generation spec: operator conventions as referenced documents.
+ * The index lists what is actually on disk at the configured conventions
+ * path; contexture ships no seeds here — conventions are definitionally
+ * operator-authored, so an empty store's section explains the mechanism.
+ */
+export declare const AGENTS_MD_CONVENTIONS_FENCE: import("./markers.js").Fence;
+export declare function renderConventionsSection(config: StoreConfig, conventions: readonly ScannedDoc[]): string[];
+export declare function buildAgentsConventionsSection(root: string, config: StoreConfig): Promise<{
+    changed: boolean;
+}>;
+/**
+ * agent-identity spec (contexture-home-layout): identity reachable open-box
+ * — a harness with no identity-injection adapter that reads only AGENTS.md
+ * still learns which files carry identity and that they load at session
+ * start. References by path only, never inlined content, so editing an
+ * identity file never requires regenerating this section.
+ */
+export declare const AGENTS_MD_IDENTITY_FENCE: import("./markers.js").Fence;
+export declare function renderIdentitySection(config: StoreConfig): string[];
+export declare function buildAgentsIdentitySection(root: string, config: StoreConfig): Promise<{
+    changed: boolean;
+}>;
+//# sourceMappingURL=agents-doc.d.ts.map

package/dist/core/agents-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-doc.d.ts","sourceRoot":"","sources":["../../src/core/agents-doc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMpE;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,8BAA4C,CAAC;AAErF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAiBrE;AAED,mHAAmH;AACnH,wBAAsB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAEnH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,8BAAyC,CAAC;AAE9E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAoBlE;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAEhH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,8BAAgC,CAAC;AAEvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CA8BpE;AAED,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAElH;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,8BAAgC,CAAC;AAEvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,EAAE,CAiCvG;AAED,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAGlH;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,8BAAwC,CAAC;AAEjF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,EAAE,CAe1G;AAED,wBAAsB,6BAA6B,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAGpH;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,8BAAqC,CAAC;AAE3E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAanE;AAED,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAEjH"}

package/dist/core/agents-doc.js

@@ -0,0 +1,207 @@
+import path from 'node:path';
+import { CONFIG_FILE_NAME } from './root.js';
+import { excludedPrefixesFor } from './notes/list.js';
+import { scanConventions } from './conventions.js';
+import { identityFilePaths } from './identity.js';
+import { scanProcedures } from './procedures.js';
+import { upsertFencedRegionInFile } from './fs/fenced-region.js';
+import { htmlCommentFence } from './markers.js';
+/**
+ * context-retrieval spec (task 4.5): the leg-routing rule that tells an
+ * agent which of its two retrieval legs to use for a given question — the
+ * catalog/graph (contexture-built-and-maintained) or its own direct content
+ * matching (grep, scoped by the store's declared exclusion paths). This is
+ * one fenced region within AGENTS.md; Phase 8 adds the canonical template's
+ * other sections (root-resolution, frontmatter schema, write-path, procedure
+ * index) as sibling regions in the same file, never touching this one.
+ */
+export const AGENTS_MD_LEG_ROUTING_FENCE = htmlCommentFence('retrieval-leg-routing');
+export function agentsMdPath(root) {
+    return path.join(root, 'AGENTS.md');
+}
+export function renderLegRoutingSection(config) {
+    const exclusions = [...new Set(excludedPrefixesFor(config))];
+    return [
+        '## Retrieval: which leg to use',
+        '',
+        'contexture builds and maintains two retrieval tools ahead of time — consult them first:',
+        '',
+        '- **Catalog** (`ctxr catalog show --section <id>`): a curated, coverage-guaranteed index of every retrievable note, one section per taxonomy layer.',
+        '- **Graph** (`ctxr graph query ...`): the wikilink graph between notes — neighbors, shortest path, hubs, orphans.',
+        '',
+        'For a literal or entity question the catalog and graph do not answer (a specific string, an exact identifier, a phrase),',
+        'use your own direct content-matching tool (e.g. grep/ripgrep) against the store, scoped to exclude:',
+        '',
+        ...exclusions.map((prefix) => `- \`${prefix}\``),
+        '',
+        'There is no `ctxr search` command. Ranked or semantic search is deferred to a future version — do not look for one.',
+    ];
+}
+/** Idempotently reconciles AGENTS.md's leg-routing section from current config — called at init and on re-init. */
+export async function buildAgentsLegRoutingSection(root, config) {
+    return upsertFencedRegionInFile(agentsMdPath(root), AGENTS_MD_LEG_ROUTING_FENCE, renderLegRoutingSection(config));
+}
+/**
+ * context-ingest spec (task 6.3): capture is a plain file write an agent
+ * does directly with its own tools — no CLI command wraps it, the same
+ * "agents gather, the CLI computes/writes/verifies" split that dropped
+ * `ctxr search`. This section documents the one rule that write must
+ * follow, so it isn't only tribal knowledge: no source-identity fields, and
+ * where the file goes.
+ */
+export const AGENTS_MD_CAPTURE_FENCE = htmlCommentFence('capture-and-ingest');
+export function renderCaptureSection(config) {
+    return [
+        '## Capturing and ingesting new material',
+        '',
+        `To capture something new, write a plain markdown file directly into \`${config.ingest.inbox_path}\` —`,
+        'no CLI command wraps this. That file MUST NOT contain any of these frontmatter fields; contexture assigns',
+        'them once, at ingest, and never before:',
+        '',
+        '- `source_type`',
+        '- `source_id`',
+        '- `source_hash`',
+        '- `ingested`',
+        '',
+        'Before ingesting, run `ctxr source check <path> --source-id <id>` to get one of four verdicts:',
+        '`new`, `already_ingested`, `alternate_source_match`, or `multiple_matches` — the last one means stop and',
+        'resolve the ambiguity yourself rather than guessing which existing note it is.',
+        '',
+        'To ingest, run `ctxr ingest <path> --source-type <type> --source-id <id>`. It stamps the four fields',
+        'above onto the file in place and rebuilds the catalog, so the result already has a catalog entry.',
+    ];
+}
+export async function buildAgentsCaptureSection(root, config) {
+    return upsertFencedRegionInFile(agentsMdPath(root), AGENTS_MD_CAPTURE_FENCE, renderCaptureSection(config));
+}
+/**
+ * context-organize spec (task 7.1): the placement procedure is
+ * documentation driven entirely by the configured taxonomy, never a
+ * hardcoded layout — this section is generated purely from
+ * `config.taxonomy.layers`, so it reads correctly under PARA, Zettelkasten,
+ * Diátaxis, or any custom taxonomy without a single layer name appearing in
+ * this file's own source.
+ */
+export const AGENTS_MD_PLACEMENT_FENCE = htmlCommentFence('placement');
+export function renderPlacementSection(config) {
+    const { layers } = config.taxonomy;
+    if (layers.length === 0) {
+        return [
+            '## Placing a new note',
+            '',
+            'This store\'s taxonomy declares no top-level layers — place new notes directly at the store root (or',
+            'wherever related notes already live) and rely on wikilinks and `ctxr graph` for organization,',
+            'rather than a folder hierarchy.',
+        ];
+    }
+    const lines = [
+        '## Placing a new note',
+        '',
+        'This store\'s taxonomy declares these layers — choose the one whose description best matches the note:',
+        '',
+    ];
+    for (const layer of layers) {
+        const directoryDefault = Object.entries(config.visibility.directory_defaults).find(([prefix]) => prefix === layer.path || prefix === `${layer.path}/`)?.[1];
+        lines.push(`- **${layer.name}** (\`${layer.path}/\`): ${layer.description}${directoryDefault ? ` Notes here default to visibility "${directoryDefault}" unless given an explicit value.` : ''}`);
+    }
+    lines.push('', "If no layer fits, use the store's uncategorized/catch-all location and revisit placement later.");
+    return lines;
+}
+export async function buildAgentsPlacementSection(root, config) {
+    return upsertFencedRegionInFile(agentsMdPath(root), AGENTS_MD_PLACEMENT_FENCE, renderPlacementSection(config));
+}
+/**
+ * harness-portability spec (task 8.5): the canonical template's four
+ * required pieces — root-resolution rule, frontmatter schema pointer,
+ * write-path rule, and a procedure index — so an agent that has read only
+ * this file, with no harness-specific context, has everything it needs
+ * (the spec's own "Reading only AGENTS.md is sufficient" scenario).
+ */
+export const AGENTS_MD_CANONICAL_FENCE = htmlCommentFence('canonical');
+export function renderCanonicalSection(config, procedures) {
+    const lines = [
+        '## Store fundamentals',
+        '',
+        '### Root resolution',
+        '',
+        `Every contexture command resolves the store root in this order: an explicit ` +
+            '`--root <path>` flag; the `CONTEXTURE_ROOT` environment variable; walking up from the current directory ' +
+            `looking for \`${CONFIG_FILE_NAME}\`. No other flag or environment variable selects the root.`,
+        '',
+        '### Frontmatter schema',
+        '',
+        `- Visibility field: \`${config.fields.visibility}:\` — resolves explicit value, then directory default, then the ` +
+            `configured fail-closed default (\`${config.visibility.default_context}\`). See \`ctxr note resolve <path>\`.`,
+        '- Source-identity fields (assigned only by `ctxr ingest`, never hand-written): `source_type`, `source_id`, `source_hash`, `ingested`.',
+        '- Disclosure audience tags (optional, hand-written): `audience: [<name>, ...]`.',
+        '',
+        '### Write path',
+        '',
+        'Every write to this store happens inside a session worktree, never directly on the default branch: `ctxr ' +
+            'session start` creates one, then `ctxr session submit` validates, commits, pushes, and opens (or ' +
+            'reports how to open) a pull request. Do not edit files in the store root directly.',
+        '',
+        '### Procedure index',
+        '',
+        'Judgment-driven operations, documented as portable markdown under ' +
+            `\`${config.harness.procedures_path}\` — read one directly, no harness-specific discovery required:`,
+        '',
+    ];
+    for (const procedure of procedures) {
+        lines.push(`- [${procedure.title}](${procedure.path})${procedure.description ? ` — ${procedure.description}` : ''}`);
+    }
+    return lines;
+}
+export async function buildAgentsCanonicalSection(root, config) {
+    const procedures = await scanProcedures(root, config);
+    return upsertFencedRegionInFile(agentsMdPath(root), AGENTS_MD_CANONICAL_FENCE, renderCanonicalSection(config, procedures));
+}
+/**
+ * entry-doc-generation spec: operator conventions as referenced documents.
+ * The index lists what is actually on disk at the configured conventions
+ * path; contexture ships no seeds here — conventions are definitionally
+ * operator-authored, so an empty store's section explains the mechanism.
+ */
+export const AGENTS_MD_CONVENTIONS_FENCE = htmlCommentFence('store-conventions');
+export function renderConventionsSection(config, conventions) {
+    const lines = ['## Store conventions', ''];
+    if (conventions.length === 0) {
+        lines.push(`This store declares no convention documents yet. Operator-authored conventions (content style, field`, `semantics, house rules) belong as markdown files under \`${config.harness.conventions_path}\` — each is`, 'indexed here on regeneration, referenced by path, never inlined.');
+        return lines;
+    }
+    lines.push('Operator-authored conventions for this store — read the ones relevant to your task:', '');
+    for (const doc of conventions) {
+        lines.push(`- [${doc.title}](${doc.path})${doc.description ? ` — ${doc.description}` : ''}`);
+    }
+    return lines;
+}
+export async function buildAgentsConventionsSection(root, config) {
+    const conventions = await scanConventions(root, config);
+    return upsertFencedRegionInFile(agentsMdPath(root), AGENTS_MD_CONVENTIONS_FENCE, renderConventionsSection(config, conventions));
+}
+/**
+ * agent-identity spec (contexture-home-layout): identity reachable open-box
+ * — a harness with no identity-injection adapter that reads only AGENTS.md
+ * still learns which files carry identity and that they load at session
+ * start. References by path only, never inlined content, so editing an
+ * identity file never requires regenerating this section.
+ */
+export const AGENTS_MD_IDENTITY_FENCE = htmlCommentFence('agent-identity');
+export function renderIdentitySection(config) {
+    const paths = identityFilePaths(config);
+    return [
+        '## Agent identity — load at session start',
+        '',
+        'This store carries durable agent identity as plain files. Before doing anything else in a session,',
+        'read all three (harnesses with a native injection mechanism may already have loaded them for you):',
+        '',
+        ...paths.map((p) => `- \`${p}\``),
+        '',
+        'They are identity, not knowledge: excluded from every retrieval leg, and never edited as part of',
+        'ordinary note work.',
+    ];
+}
+export async function buildAgentsIdentitySection(root, config) {
+    return upsertFencedRegionInFile(agentsMdPath(root), AGENTS_MD_IDENTITY_FENCE, renderIdentitySection(config));
+}
+//# sourceMappingURL=agents-doc.js.map

package/dist/core/agents-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-doc.js","sourceRoot":"","sources":["../../src/core/agents-doc.ts"],"names":[],"mappings":"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"}

package/dist/core/catalog/build.d.ts

@@ -0,0 +1,49 @@
+import type { Store } from '../store.js';
+import { type CatalogSection } from './model.js';
+export declare const CATALOG_FENCE: import("../markers.js").Fence;
+export interface CatalogSectionBuildResult {
+    id: string;
+    file: string;
+    noteCount: number;
+    changed: boolean;
+}
+export interface CatalogBuildResult {
+    sections: CatalogSectionBuildResult[];
+    totalNotes: number;
+}
+/**
+ * context-catalog spec: regenerates each section's fenced identity/path
+ * entries, preserving any already-authored gloss. Re-running with no
+ * underlying change is byte-identical (upsertFencedRegionInFile only writes
+ * when content actually differs).
+ */
+export declare function buildCatalog(store: Store): Promise<CatalogBuildResult>;
+export interface CatalogCoverageResult {
+    /** Retrievable notes with no catalog entry anywhere. */
+    missing: string[];
+    /** Catalog entries referencing a path that is no longer a retrievable note (e.g. deleted). */
+    dangling: string[];
+}
+/**
+ * context-catalog spec: coverage is a hard invariant in BOTH directions —
+ * every retrievable note must have an entry (missing), and every entry must
+ * still reference a real, retrievable note (dangling). A deleted note whose
+ * stale entry survives a build is exactly the failure this second half
+ * catches — `catalog build` only ever ADDS/preserves entries, so removal
+ * must be caught here rather than silently left to rot.
+ */
+export declare function checkCatalogCoverage(store: Store): Promise<CatalogCoverageResult>;
+export interface CatalogStaleEntry {
+    path: string;
+    section: string;
+}
+/** context-catalog spec: an entry whose note has changed since its gloss was confirmed needs review. */
+export declare function checkCatalogStale(store: Store): Promise<CatalogStaleEntry[]>;
+/**
+ * Returns null ONLY when `sectionId` doesn't name a configured section — a
+ * real section that simply hasn't been built yet (or has no notes) returns
+ * an empty string, which is a valid, uninteresting result, not an error.
+ */
+export declare function readCatalogSection(store: Store, sectionId: string, asContext?: string): Promise<string | null>;
+export declare function catalogSectionPath(store: Store, section: CatalogSection): string;
+//# sourceMappingURL=build.d.ts.map

package/dist/core/catalog/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/core/catalog/build.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,aAAa,+BAA8B,CAAC;AAoBzD,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmB5E;AAED,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgBvF;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wGAAwG;AACxG,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAmBlF;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMpH;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAEhF"}