@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/init/render.d.ts

@@ -2,24 +2,36 @@ import type { CockpitConfig, configurationDefaults, UNCONFIRMABLE_ANSWERS } from
 import type { DocumentedSibling, Gap } from '../registry-resolve/registry.js';
 /**
  * Who gave an interview answer: a person, the setup agent choosing a default it was allowed to
- * choose, or no one said (an answers file that does not attribute a value cockpit never proposes).
- * Only a person's answer is written as stated; the others are listed under `unconfirmed`.
+ * choose, no one said (an answers file that does not attribute a value cockpit never proposes), or
+ * the setup agent accepting the value init read from exact sources, which init checks against what
+ * it reads. A person's answer is written as stated and a derived one with its source; the others
+ * are listed under `unconfirmed`.
  */
-export declare const ANSWER_PROVENANCES: readonly ['operator-confirmed', 'agent-default', 'unattributed'];
+export declare const ANSWER_PROVENANCES: readonly ['operator-confirmed', 'agent-default', 'unattributed', 'derived'];
 export type AnswerProvenance = typeof ANSWER_PROVENANCES[number];
 export type UnconfirmableAnswer = typeof UNCONFIRMABLE_ANSWERS[number];
 export type UnconfirmedAnswer = Readonly<{
     field: UnconfirmableAnswer;
-    provenance: Exclude<AnswerProvenance, 'operator-confirmed'>;
+    provenance: 'agent-default' | 'unattributed';
+}>;
+/** An answer accepted as read: the field and the file, as file:line where one line holds it, it was read from. */
+export type DerivedAnswer = Readonly<{
+    field: UnconfirmableAnswer;
+    source: string;
 }>;
 export declare function unconfirmedReason(row: UnconfirmedAnswer): string;
-export declare const UNCONFIRMED_FIX = "confirm the value with whoever owns the product and correct it in cockpit.toml if it is wrong, then delete its entry from unconfirmed and run npx --no cockpit sync --config <your cockpit.toml>";
 export interface Attribution {
     target: string;
     value: unknown;
     from: 'inferred' | 'default';
     because: string;
 }
+/**
+ * Who confirms a surfaced value: the setup agent for a schema default or the cockpit's own layout,
+ * which bring-up proves, and a person for a security boundary or a value a registry dialect left
+ * to a guess.
+ */
+export declare function confirmedBy(attribution: Attribution): 'agent' | 'person';
 export interface DocumentModel {
     name?: string;
     defaults: ReturnType<typeof configurationDefaults>;
@@ -32,4 +44,4 @@ export interface DocumentModel {
 }
 export declare function renderIncompleteDocument(model: DocumentModel, schemaDirective: string, configuration?: CockpitConfig): string;
 /** Decisions are comments: the schema has no field for them, and the reader of the file needs them. */
-export declare function renderCompleteDocument(config: CockpitConfig, schemaDirective: string, decisions?: readonly string[], unconfirmed?: readonly UnconfirmedAnswer[]): string;
+export declare function renderCompleteDocument(config: CockpitConfig, schemaDirective: string, decisions?: readonly string[], unconfirmed?: readonly UnconfirmedAnswer[], derived?: readonly DerivedAnswer[]): string;

package/dist/init/render.js

@@ -1,21 +1,26 @@
 import { AUTONOMY_DEFAULTS, GATE_DEFAULTS } from '../autonomy.js';
+import { unconfirmedFix } from '../guards/answer-confirmation.js';
 import { emitGaps, emitToml, toSiblingRows } from '../emit.js';
 /**
  * Who gave an interview answer: a person, the setup agent choosing a default it was allowed to
- * choose, or no one said (an answers file that does not attribute a value cockpit never proposes).
- * Only a person's answer is written as stated; the others are listed under `unconfirmed`.
+ * choose, no one said (an answers file that does not attribute a value cockpit never proposes), or
+ * the setup agent accepting the value init read from exact sources, which init checks against what
+ * it reads. A person's answer is written as stated and a derived one with its source; the others
+ * are listed under `unconfirmed`.
  */
-export const ANSWER_PROVENANCES = ['operator-confirmed', 'agent-default', 'unattributed'];
+export const ANSWER_PROVENANCES = ['operator-confirmed', 'agent-default', 'unattributed', 'derived'];
 export function unconfirmedReason(row) {
     return row.provenance === 'agent-default'
         ? `${row.field} was chosen by the setup agent as a default; no person stated it`
         : `${row.field} came from an answers file that did not say who chose it; no person is known to have stated it`;
 }
-export const UNCONFIRMED_FIX = 'confirm the value with whoever owns the product and correct it in cockpit.toml if it is wrong, then delete its entry from unconfirmed and run npx --no cockpit sync --config <your cockpit.toml>';
 function renderUnconfirmed(rows = []) {
     if (rows.length === 0)
         return '';
-    return `${rows.map(row => `# Unconfirmed: ${unconfirmedReason(row)}.\n`).join('')}# To confirm: ${UNCONFIRMED_FIX}; until then doctor warns.\n`;
+    return `${rows.map(row => `# Unconfirmed: ${unconfirmedReason(row)}.\n`).join('')}# To confirm: ${unconfirmedFix(rows.map(row => row.field))}; until then doctor warns.\n`;
+}
+function renderDerived(rows) {
+    return rows.map(row => `# Derived: ${row.field} was read from ${row.source} and accepted by the setup agent; bring-up proves it.\n`).join('');
 }
 /** Every decision with its default, commented out: flip one to "person" to take that decision yourself. */
 function renderDecisionDefaults() {
@@ -27,12 +32,29 @@ function renderDecisionDefaults() {
         ...table('work.gates', GATE_DEFAULTS), ...table('autonomy', AUTONOMY_DEFAULTS),
     ].join('\n')}\n`;
 }
+// A wrong value in one of these widens what an agent may do or delete, so a person confirms it.
+const PERSON_CONFIRMED_TARGETS = new Set(['guards.protected_branches', 'guards.allow', 'guards.deny',
+    'mcp.approved', 'environment.resettable_volumes', 'environment.generated_host_paths']);
+/**
+ * Who confirms a surfaced value: the setup agent for a schema default or the cockpit's own layout,
+ * which bring-up proves, and a person for a security boundary or a value a registry dialect left
+ * to a guess.
+ */
+export function confirmedBy(attribution) {
+    if (PERSON_CONFIRMED_TARGETS.has(attribution.target))
+        return 'person';
+    return attribution.from === 'default' || attribution.target === 'cockpit.siblings_root' ? 'agent' : 'person';
+}
 function renderAttributions(attributions) {
     if (attributions.length === 0)
         return '';
     const lines = ['# Provenance — every unread value names its source and reason.'];
-    for (const attribution of attributions) {
-        lines.push(`# [${attribution.from}] ${attribution.target} = ${JSON.stringify(attribution.value)}: ${attribution.because}`);
+    for (const [by, heading] of [['agent', '# The setup agent accepts these: schema defaults and the cockpit\'s own layout, which bring-up proves.'],
+        ['person', '# A person confirms these, and the defaults digest covers only them: each bounds what an agent may do.']]) {
+        const rows = attributions.filter(row => confirmedBy(row) === by);
+        if (rows.length === 0)
+            continue;
+        lines.push(heading, ...rows.map(row => `# [${row.from}] ${row.target} = ${JSON.stringify(row.value)}: ${row.because}`));
     }
     return `${lines.join('\n')}\n`;
 }
@@ -77,6 +99,6 @@ export function renderIncompleteDocument(model, schemaDirective, configuration)
     ].join('');
 }
 /** Decisions are comments: the schema has no field for them, and the reader of the file needs them. */
-export function renderCompleteDocument(config, schemaDirective, decisions = [], unconfirmed = []) {
-    return `#:schema ${schemaDirective}\n${decisions.map(decision => `# Decision: ${decision}\n`).join('')}${renderUnconfirmed(unconfirmed)}${emitToml(config)}${renderDecisionDefaults()}`;
+export function renderCompleteDocument(config, schemaDirective, decisions = [], unconfirmed = [], derived = []) {
+    return `#:schema ${schemaDirective}\n${decisions.map(decision => `# Decision: ${decision}\n`).join('')}${renderDerived(derived)}${renderUnconfirmed(unconfirmed)}${emitToml(config)}${renderDecisionDefaults()}`;
 }

package/dist/repository-path.d.ts

@@ -0,0 +1,9 @@
+/** A path or glob (`*`, `?`, `**`), optionally `<slug>:`-prefixed, without `..` segments or a leading `/`. */
+export declare const REPOSITORY_PATH: RegExp;
+/** One file or directory, optionally `<slug>:`-prefixed: no wildcards, no `.` or `..` segments, no leading or trailing `/`. */
+export declare const REPOSITORY_FILE: RegExp;
+/** The sibling a reference names, if any, and the path inside that repository. */
+export declare function splitRepositoryPath(reference: string): Readonly<{
+    slug?: string;
+    path: string;
+}>;

package/dist/repository-path.js

@@ -0,0 +1,16 @@
+// A path in one of a cockpit's repositories: `path` in the cockpit's own, or `<sibling slug>:path` in a
+// sibling. Work-order scopes and sources, the [docs] declarations and every reader of them spell and
+// split it here, so a reference one admits is the reference the other resolves.
+const SLUG = '[a-z0-9][a-z0-9-]{0,63}';
+// Never absolute or climbing. The climbing check looks past the sibling prefix, which would otherwise
+// consume the `:` before `..`.
+/** A path or glob (`*`, `?`, `**`), optionally `<slug>:`-prefixed, without `..` segments or a leading `/`. */
+export const REPOSITORY_PATH = new RegExp(`^(?!(?:${SLUG}:)?(?:.*/)?\\.\\.(?:/|$))(?:${SLUG}:)?(?![/])[A-Za-z0-9._@+\\-/*?]+$`);
+/** One file or directory, optionally `<slug>:`-prefixed: no wildcards, no `.` or `..` segments, no leading or trailing `/`. */
+export const REPOSITORY_FILE = new RegExp(`^(?!(?:${SLUG}:)?(?:.*/)?\\.\\.?(?:/|$))(?:${SLUG}:)?(?![/])[A-Za-z0-9._@+\\-/]*[A-Za-z0-9._@+-]$`);
+const PREFIXED = new RegExp(`^(${SLUG}):(.*)$`);
+/** The sibling a reference names, if any, and the path inside that repository. */
+export function splitRepositoryPath(reference) {
+    const match = PREFIXED.exec(reference);
+    return match ? { slug: match[1], path: match[2] } : { path: reference };
+}

package/dist/schema.d.ts

@@ -16,15 +16,6 @@ export declare const AuthPosture: z.ZodEnum<{
     none: "none";
     real: "real";
 }>;
-declare const Toolchain: z.ZodEnum<{
-    dotnet: "dotnet";
-    go: "go";
-    node: "node";
-    none: "none";
-    python: "python";
-    ruby: "ruby";
-    rust: "rust";
-}>;
 export declare const EnvironmentFile: z.ZodObject<{
     template: z.ZodString;
     instance: z.ZodString;
@@ -37,6 +28,8 @@ export declare const MachineFloor: z.ZodObject<{
     cold_start_seconds: z.ZodNumber;
 }, z.core.$strict>;
 export declare const ResettableVolumeId: z.ZodString;
+/** A Compose profile name, in the lowercase spelling every stack command and state record shares. */
+export declare const ComposeProfileName: z.ZodString;
 export declare const GeneratedHostPath: z.ZodString;
 export declare function parseBrowserNetworkExposure(value: string | undefined, reason: string | undefined): Readonly<{
     value: string;
@@ -116,6 +109,7 @@ export declare const Environment: z.ZodObject<{
     resettable_volumes: z.ZodDefault<z.ZodArray<z.ZodString>>;
     generated_host_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
     compose_files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    profiles: z.ZodDefault<z.ZodArray<z.ZodString>>;
     entrypoint_derivatives: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         kind: z.ZodEnum<{
@@ -191,6 +185,7 @@ export declare const Sibling: z.ZodObject<{
         template: z.ZodString;
         instance: z.ZodString;
     }, z.core.$strict>>>;
+    rebuild_inputs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     derives: z.ZodOptional<z.ZodObject<{
         mcp_sources: z.ZodArray<z.ZodObject<{
             path: z.ZodString;
@@ -275,6 +270,11 @@ export declare const Work: z.ZodObject<{
             ci: "ci";
             person: "person";
         }>>;
+        acknowledge: z.ZodOptional<z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const Autonomy: z.ZodObject<{
@@ -301,6 +301,12 @@ export declare const Autonomy: z.ZodObject<{
 export declare const BROWSER_DRIVER_VERSION: RegExp;
 /** Playwright refuses a client and server whose major.minor differ, so only that much must agree. */
 export declare function browserDriversCompatible(left: string, right: string): boolean;
+/** The data posture that lets browser tools run without prompts: isolated, not restored, not reaching production. */
+export declare const browserDataQualifies: (data: Readonly<{
+    mode: string;
+    isolated: boolean;
+    reaches_production: boolean;
+}>) => boolean;
 export declare const Browser: z.ZodObject<{
     engine: z.ZodDefault<z.ZodEnum<{
         chromium: "chromium";
@@ -366,7 +372,7 @@ export declare const Browser: z.ZodObject<{
         isolated: z.ZodBoolean;
         reaches_production: z.ZodBoolean;
     }, z.core.$strict>;
-    request_preapproval: z.ZodDefault<z.ZodBoolean>;
+    request_preapproval: z.ZodOptional<z.ZodBoolean>;
     artifacts: z.ZodObject<{
         mcp: z.ZodString;
         cli: z.ZodString;
@@ -375,6 +381,7 @@ export declare const Browser: z.ZodObject<{
 }, z.core.$strict>;
 export declare const TestingName: z.ZodString;
 export declare const Testing: z.ZodObject<{
+    test_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
     stages: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         command: z.ZodArray<z.ZodString>;
@@ -407,14 +414,6 @@ export declare const Testing: z.ZodObject<{
         sha256: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-declare const SurfaceSource: z.ZodObject<{
-    path: z.ZodIntersection<z.ZodString, z.ZodString>;
-    bytes: z.ZodString;
-}, z.core.$strict>;
-declare const SurfaceOverrideReference: z.ZodObject<{
-    name: z.ZodString;
-    sha256: z.ZodString;
-}, z.core.$strict>;
 export declare const SurfaceDeclaration: z.ZodObject<{
     name: z.ZodString;
     feature: z.ZodEnum<{
@@ -474,57 +473,6 @@ export declare const SurfaceAdoption: z.ZodObject<{
         confirmed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
 }, z.core.$strict>;
-declare const CustomHarnessCapability: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    feature: z.ZodEnum<{
-        hooks: "hooks";
-        mcp: "mcp";
-        permissions: "permissions";
-        rules: "rules";
-        skills: "skills";
-        subagents: "subagents";
-    }>;
-    measured_on: z.ZodString;
-    spelling: z.ZodIntersection<z.ZodString, z.ZodString>;
-    control: z.ZodIntersection<z.ZodString, z.ZodString>;
-    mechanism: z.ZodObject<{
-        module: z.ZodIntersection<z.ZodString, z.ZodString>;
-        export: z.ZodString;
-    }, z.core.$strict>;
-    state: z.ZodLiteral<"enforced">;
-    evidence: z.ZodObject<{
-        reference: z.ZodIntersection<z.ZodString, z.ZodString>;
-        sha256: z.ZodString;
-    }, z.core.$strict>;
-}, z.core.$strict>, z.ZodObject<{
-    feature: z.ZodEnum<{
-        hooks: "hooks";
-        mcp: "mcp";
-        permissions: "permissions";
-        rules: "rules";
-        skills: "skills";
-        subagents: "subagents";
-    }>;
-    measured_on: z.ZodString;
-    spelling: z.ZodIntersection<z.ZodString, z.ZodString>;
-    control: z.ZodIntersection<z.ZodString, z.ZodString>;
-    mechanism: z.ZodObject<{
-        module: z.ZodIntersection<z.ZodString, z.ZodString>;
-        export: z.ZodString;
-    }, z.core.$strict>;
-    state: z.ZodLiteral<"instructed">;
-}, z.core.$strict>, z.ZodObject<{
-    feature: z.ZodEnum<{
-        hooks: "hooks";
-        mcp: "mcp";
-        permissions: "permissions";
-        rules: "rules";
-        skills: "skills";
-        subagents: "subagents";
-    }>;
-    measured_on: z.ZodString;
-    state: z.ZodLiteral<"unavailable">;
-    reason: z.ZodString;
-}, z.core.$strict>], "state">;
 export declare const CustomHarness: z.ZodObject<{
     name: z.ZodString;
     capabilities: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -732,6 +680,7 @@ export declare function configurationDefaults(): {
             amend?: "agent" | "ci" | "person" | undefined;
             answer?: "agent" | "ci" | "person" | undefined;
             signoff?: "agent" | "ci" | "person" | undefined;
+            acknowledge?: "agent" | "ci" | "person" | undefined;
         };
     };
     autonomy: {
@@ -757,6 +706,7 @@ export declare function configurationDefaults(): {
         resettable_volumes: string[];
         generated_host_paths: string[];
         compose_files: string[];
+        profiles: string[];
         entrypoint_derivatives: {
             name: string;
             kind: "advertised_listener" | "callback_url" | "cors_origin" | "entrypoint" | "origin" | "public_base_url";
@@ -847,6 +797,11 @@ export declare function configurationDefaults(): {
  * stated but were guessed is the failure cockpit exists to prevent.
  */
 export declare const UNCONFIRMABLE_ANSWERS: readonly ['cockpit.name', 'sibling', 'estate.runnable', 'ports.bases', 'environment.install_policies', 'environment.test_data', 'environment.compose_files', 'environment.machine', 'environment.posture', 'testing', 'guards'];
+export declare const Docs: z.ZodObject<{
+    living: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    decisions: z.ZodOptional<z.ZodString>;
+    decisions_index: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const CockpitConfig: z.ZodObject<{
     unconfirmed: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         "cockpit.name": "cockpit.name";
@@ -898,6 +853,7 @@ export declare const CockpitConfig: z.ZodObject<{
             template: z.ZodString;
             instance: z.ZodString;
         }, z.core.$strict>>>;
+        rebuild_inputs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         derives: z.ZodOptional<z.ZodObject<{
             mcp_sources: z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
@@ -978,6 +934,11 @@ export declare const CockpitConfig: z.ZodObject<{
                 ci: "ci";
                 person: "person";
             }>>;
+            acknowledge: z.ZodOptional<z.ZodEnum<{
+                agent: "agent";
+                ci: "ci";
+                person: "person";
+            }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
     autonomy: z.ZodPrefault<z.ZodObject<{
@@ -1066,7 +1027,7 @@ export declare const CockpitConfig: z.ZodObject<{
             isolated: z.ZodBoolean;
             reaches_production: z.ZodBoolean;
         }, z.core.$strict>;
-        request_preapproval: z.ZodDefault<z.ZodBoolean>;
+        request_preapproval: z.ZodOptional<z.ZodBoolean>;
         artifacts: z.ZodObject<{
             mcp: z.ZodString;
             cli: z.ZodString;
@@ -1074,6 +1035,7 @@ export declare const CockpitConfig: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>>;
     testing: z.ZodOptional<z.ZodObject<{
+        test_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
         stages: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             command: z.ZodArray<z.ZodString>;
@@ -1137,6 +1099,7 @@ export declare const CockpitConfig: z.ZodObject<{
         resettable_volumes: z.ZodDefault<z.ZodArray<z.ZodString>>;
         generated_host_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
         compose_files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        profiles: z.ZodDefault<z.ZodArray<z.ZodString>>;
         entrypoint_derivatives: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             kind: z.ZodEnum<{
@@ -1278,11 +1241,15 @@ export declare const CockpitConfig: z.ZodObject<{
             }, z.core.$strict>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    docs: z.ZodOptional<z.ZodObject<{
+        living: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        decisions: z.ZodOptional<z.ZodString>;
+        decisions_index: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type CockpitConfig = z.infer<typeof CockpitConfig>;
 export type Sibling = z.infer<typeof Sibling>;
 export type Acquire = z.infer<typeof Acquire>;
-export type Toolchain = z.infer<typeof Toolchain>;
 export type AddressingPosture = z.infer<typeof AddressingPosture>;
 export type AuthPosture = z.infer<typeof AuthPosture>;
 export type EnvironmentFile = z.infer<typeof EnvironmentFile>;
@@ -1293,17 +1260,17 @@ export type EntrypointDerivative = z.infer<typeof EntrypointDerivative>;
 export type InstallPolicy = z.infer<typeof InstallPolicy>;
 export type Browser = z.infer<typeof Browser>;
 export type Testing = z.infer<typeof Testing>;
+export type Docs = z.infer<typeof Docs>;
 export type Provenance = z.infer<typeof Provenance>;
-export type SurfaceSource = z.infer<typeof SurfaceSource>;
-export type SurfaceOverrideReference = z.infer<typeof SurfaceOverrideReference>;
 export type SurfaceDeclaration = z.infer<typeof SurfaceDeclaration>;
 export type SurfaceOverlay = z.infer<typeof SurfaceOverlay>;
 export type SurfaceAdoption = z.infer<typeof SurfaceAdoption>;
-export type CustomHarnessCapability = z.infer<typeof CustomHarnessCapability>;
 export type CustomHarness = z.infer<typeof CustomHarness>;
 export type Surfaces = z.infer<typeof Surfaces>;
 /** Rows the stack bind-mounts under the given profile set — the projection's import list. */
-export declare function mounted(cfg: CockpitConfig, profiles: readonly string[]): Sibling[];
+export declare function mounted<Row extends Readonly<Pick<Sibling, 'mount'>>>(cfg: Readonly<{
+    sibling: readonly Row[];
+}>, profiles: readonly string[]): Row[];
 /**
  * The SHA-256 that identifies a running stack: ownership labels, the generation, saved progress and
  * data history are keyed by it rather than by the bytes of cockpit.toml. Keying them by the file

package/dist/schema.js

@@ -8,6 +8,7 @@ import { GUARD_HOST_LIMITS, GUARD_HOST_PATTERN, normalizeGuardHost } from './gua
 import { ADOPTABLE_SURFACE_PATHS, ADOPTED_SURFACE_ROOT, SURFACE_BUNDLE_FORMATS, SURFACE_FEATURES, SURFACE_TARGETS, surfaceSourcesMatchFeature } from './surfaces/contract.js';
 import { DEFAULT_SURFACE_TOOLS, GUARD_SURFACE_TARGETS } from './surfaces/harness-registry.js';
 import { RefusalError, errorCause } from './environment/contract.js';
+import { REPOSITORY_FILE, REPOSITORY_PATH, splitRepositoryPath } from './repository-path.js';
 export const STRUCTURED_INPUT_ENTRY_LIMIT = 4_096;
 // Zod cannot reflect a regex in a string type; successful parses satisfy this narrower output.
 export const Mount = z
@@ -57,6 +58,8 @@ export const MachineFloor = z
 })
     .strict();
 export const ResettableVolumeId = z.string().regex(/^[a-z0-9][a-z0-9_.-]*$/);
+/** A Compose profile name, in the lowercase spelling every stack command and state record shares. */
+export const ComposeProfileName = z.string().max(64).regex(/^[a-z0-9][a-z0-9_.-]*$/, 'expected a lowercase Compose profile name');
 export const GeneratedHostPath = SafeRelativePath;
 export function parseBrowserNetworkExposure(value, reason) {
     const exposure = value ?? '<loopback>';
@@ -151,6 +154,7 @@ export const Environment = z
     resettable_volumes: z.array(ResettableVolumeId).default([]).describe('Compose volumes that reset may delete and recreate, named by their Compose key.'),
     generated_host_paths: z.array(GeneratedHostPath).default([]).describe('Host paths cockpit generates and owns, relative to the cockpit.'),
     compose_files: z.array(LocalComposePath).default([]).describe('Compose files, relative to the cockpit, that make up the stack; cockpit runs them as written.'),
+    profiles: z.array(ComposeProfileName).max(64).default([]).describe('Compose profiles every up and session activates; up --profile adds more for one run.'),
     entrypoint_derivatives: z.array(EntrypointDerivative).default([]).describe('Addresses derived from leased ports, such as application origins and callback URLs.'),
     install_policies: z.array(InstallPolicy).default([]).describe('The build and test commands the guard admits for each toolchain and lockfile.'),
     // Product data lives in the resettable volumes, so the seed reruns exactly when one of them is
@@ -166,6 +170,7 @@ export const Environment = z
         resettable_volumes: environment.resettable_volumes,
         generated_host_paths: environment.generated_host_paths,
         compose_files: environment.compose_files,
+        profiles: environment.profiles,
         entrypoint_derivatives: environment.entrypoint_derivatives.map((row) => row.name),
         posture_requirements: environment.posture_requirements?.map((row) => row.requirement) ?? [],
     };
@@ -256,6 +261,9 @@ export const Sibling = z
     // Printed when the checkout is missing, so it says what the absence costs.
     purpose: z.string().min(1).describe('What the sibling is for; printed when its checkout is missing.'),
     environment_files: z.array(EnvironmentFile).optional().describe('Template and instance environment file pairs the sibling needs.'),
+    // A running stack keeps the dependencies and schema it started with; a pulled lockfile or a new
+    // migration behind it fails like a product bug. Lockfiles are watched without this list.
+    rebuild_inputs: z.array(SafeRelativePath).max(64).optional().describe('Files or directories in the sibling, beyond its lockfiles, whose change leaves a running stack stale, such as a migrations directory.'),
     derives: SiblingDerives.optional().describe('Facts about the sibling that cockpit derives rows or MCP servers from.'),
 })
     .strict()
@@ -388,9 +396,10 @@ export const WORK_GRADING = ['independent', 'checks', 'self'];
 const WorkGates = z
     .object({
     accept: Decider.optional().describe('Who accepts a draft work order: agent, person or ci. Default agent.'),
-    amend: Decider.optional().describe('Who accepts a changed contract. Default agent. Removing or rewriting an accepted criterion always needs a person or ci.'),
+    amend: Decider.optional().describe('Who accepts a changed contract. Default agent. Removing an accepted criterion or gate always needs a person or ci; an agent\'s rewrite of a criterion, scope, non-goal or objective is judged at the next grade, and needs a person under checks grading.'),
     answer: Decider.optional().describe('Who answers an open question on an order. Default agent.'),
     signoff: Decider.optional().describe('Who closes a graded order. Default agent.'),
+    acknowledge: Decider.optional().describe('Who acknowledges that an order weakened tests, which checks grading otherwise fails; under independent and self grading the acknowledgement is context for the verdict. Default agent.'),
 })
     .strict();
 export const Work = z
@@ -446,6 +455,8 @@ const BrowserArtifactRoots = z.object({
         }
     }
 });
+/** The data posture that lets browser tools run without prompts: isolated, not restored, not reaching production. */
+export const browserDataQualifies = (data) => data.mode !== 'restored' && data.isolated && !data.reaches_production;
 export const Browser = z.object({
     engine: z.enum(['chromium', 'firefox', 'webkit']).default('chromium').describe('Browser engine to drive.'),
     network_exposure: z.string().min(1).max(512).regex(/^[a-z0-9.*:<>\[\],-]+$/).refine((value) => {
@@ -494,7 +505,7 @@ export const Browser = z.object({
         isolated: z.boolean().describe('True when the data is separate from anyone else\'s.'),
         reaches_production: z.boolean().describe('True when browser actions can affect production.'),
     }).strict().describe('Statement about the data the browser touches; cockpit cannot observe it.'),
-    request_preapproval: z.boolean().default(false).describe('Run browser tools without prompts; allowed only on isolated, non-production, non-restored data.'),
+    request_preapproval: z.boolean().optional().describe('Run browser tools without prompts; allowed only on isolated, non-production, non-restored data. Defaults to true when data qualifies and false otherwise.'),
     artifacts: BrowserArtifactRoots.describe('Generated host paths for browser output.'),
 }).strict().superRefine((browser, ctx) => {
     try {
@@ -538,7 +549,7 @@ export const Browser = z.object({
     if (paths.some((path) => !path.startsWith(`${browser.artifacts.auth}/`))) {
         ctx.addIssue({ code: 'custom', path: ['authentication', 'states'], message: 'browser authentication state must stay inside the auth artifact root' });
     }
-    if (browser.request_preapproval && (browser.data.mode === 'restored' || !browser.data.isolated || browser.data.reaches_production)) {
+    if (browser.request_preapproval && !browserDataQualifies(browser.data)) {
         ctx.addIssue({ code: 'custom', path: ['request_preapproval'], message: 'browser preapproval requires isolated empty or seeded data without production reach' });
     }
 });
@@ -555,6 +566,8 @@ const TestingSelect = z.object({
     route: TestingSelectArguments.optional().describe('Arguments that select tests by route; {value} becomes the selection.'),
 }).strict();
 export const Testing = z.object({
+    test_files: z.array(z.string().min(1).max(512).regex(/^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._@+\-/*?]+$/, 'a relative path or glob, without .. or a leading /')).min(1).max(64).optional()
+        .describe('Paths and globs, relative to each checkout, that hold tests. Grading fails an order that deletes, skips or loosens what they match. Defaults to common layouts.'),
     stages: z.array(z.object({
         id: TestingName.describe('Name of the stage.'),
         command: TestingCommand.describe('Command to run, as an argument list.'),
@@ -777,6 +790,27 @@ export function configurationDefaults() {
 export const UNCONFIRMABLE_ANSWERS = ['cockpit.name', 'sibling', 'estate.runnable', 'ports.bases', 'environment.install_policies',
     'environment.test_data', 'environment.compose_files', 'environment.machine', 'environment.posture',
     'testing', 'guards'];
+// `path` in the cockpit's own repository, or `<sibling slug>:path` in a sibling, spelt as a work
+// order's scope is. Living documents may be globs; the decision paths name one file or directory.
+const DocsGlob = z.string().max(1_024).regex(REPOSITORY_PATH, 'a relative path, optionally <sibling slug>:path, without .. or a leading /');
+const DocsFile = z.string().max(1_024).regex(REPOSITORY_FILE, 'one relative path without wildcards, optionally <sibling slug>:path, without . or .. segments or a leading or trailing /');
+const repositoryOf = (path) => splitRepositoryPath(path).slug ?? '.';
+export const Docs = z.object({
+    living: z.array(DocsGlob).max(64).default([])
+        .describe('Globs of the Markdown documents that must stay true; docs check reports the paths and make targets they cite that the repository has since removed.'),
+    decisions: DocsFile.optional().describe('Directory of decision records, such as docs/adr. Work orders record their lasting decisions there, and docs check reports duplicate numbers, missing statuses and broken supersedes links.'),
+    decisions_index: DocsFile.optional().describe('Index file that links every decision record; a record cockpit writes is appended to it, and docs check reports records it omits and links to records that do not exist.'),
+}).strict().superRefine((docs, ctx) => {
+    // A [docs] table that names nothing would parse and do nothing.
+    if (docs.living.length === 0 && docs.decisions === undefined)
+        ctx.addIssue({ code: 'custom', path: [], message: '[docs] declares neither living documents nor decisions' });
+    // An index with no records directory, or of another repository's records, would check nothing.
+    if (docs.decisions_index !== undefined && docs.decisions === undefined)
+        ctx.addIssue({ code: 'custom', path: ['decisions_index'], message: 'decisions_index needs decisions, the directory it indexes' });
+    else if (docs.decisions_index !== undefined && repositoryOf(docs.decisions_index) !== repositoryOf(docs.decisions)) {
+        ctx.addIssue({ code: 'custom', path: ['decisions_index'], message: 'decisions_index must be in the same repository as decisions, so its links resolve' });
+    }
+});
 export const CockpitConfig = z
     .object({
     unconfirmed: z.array(z.enum(UNCONFIRMABLE_ANSWERS)).min(1).max(UNCONFIRMABLE_ANSWERS.length)
@@ -792,6 +826,7 @@ export const CockpitConfig = z
     testing: Testing.optional().describe('Test stages and gates.'),
     environment: Environment.prefault({}).describe('How the stack is reached, signed in to, built and kept.'),
     surfaces: Surfaces.prefault({}).describe('Instructions, skills and settings generated for agent tools.'),
+    docs: Docs.optional().describe('Living documents and decision records: docs check keeps them true, and work orders record their decisions there.'),
 })
     .strict()
     .superRefine((cfg, ctx) => {
@@ -872,20 +907,36 @@ export const CockpitConfig = z
                 message: `resettable volume ${JSON.stringify(name)} names no volume: the environment declares no compose_files`,
             });
         });
+        cfg.environment.profiles.forEach((name, index) => {
+            ctx.addIssue({
+                code: 'custom', path: ['environment', 'profiles', index],
+                message: `profile ${JSON.stringify(name)} activates nothing: the environment declares no compose_files`,
+            });
+        });
+    }
+    if (cfg.docs) {
+        const paths = [...cfg.docs.living.map((path, index) => ({ path, at: ['docs', 'living', index] })),
+            ...cfg.docs.decisions === undefined ? [] : [{ path: cfg.docs.decisions, at: ['docs', 'decisions'] }],
+            ...cfg.docs.decisions_index === undefined ? [] : [{ path: cfg.docs.decisions_index, at: ['docs', 'decisions_index'] }]];
+        for (const { path, at } of paths) {
+            const slug = repositoryOf(path);
+            if (slug !== '.' && !cfg.sibling.some(row => row.slug === slug)) {
+                ctx.addIssue({ code: 'custom', path: at, message: `${JSON.stringify(path)} names sibling "${slug}", which no [[sibling]] declares` });
+            }
+        }
     }
-    // Deliberately NOT checked here: that a `profile:<name>` lane names a profile in
-    // `profiles.default`. A profile lane is opt-in by definition — it exists precisely to
-    // stay off until EXTRA_PROFILES turns it on — so absence from the default set is the
-    // normal case, not a defect. The spelling is defined by the compose file,
-    // which preflight reads and a schema cannot.
+    // Not checked here: that `environment.profiles` and each `profile:<name>` mount name a
+    // profile the Compose files define. Those names live in the Compose files, which `check`
+    // and every stack command read and a schema cannot. A profile mount outside
+    // `environment.profiles` is the normal case: it stays off until `up --profile` turns it on.
 });
 /** Rows the stack bind-mounts under the given profile set — the projection's import list. */
 export function mounted(cfg, profiles) {
     return cfg.sibling.filter((s) => s.mount === 'always' || (s.mount.startsWith('profile:') && profiles.includes(s.mount.slice(8))));
 }
-// How a sibling is described, fetched, gated for agents or projected into guides. None of it reaches
-// a container, so editing it must leave a running stack alone.
-const SIBLING_NON_RUNTIME_FIELDS = new Set(['purpose', 'guides', 'instruction_pointer', 'remote', 'branch', 'acquire', 'host_reason', 'gate']);
+// How a sibling is described, fetched, gated for agents, projected into guides or watched for a stale
+// stack. None of it reaches a container, so editing it must leave a running stack alone.
+const SIBLING_NON_RUNTIME_FIELDS = new Set(['purpose', 'guides', 'instruction_pointer', 'remote', 'branch', 'acquire', 'host_reason', 'gate', 'rebuild_inputs']);
 // What the host checks or reports around the containers: the machine floor and cold-start budget
 // `up` and preflight hold the host to, the posture preflight reads, the volumes `reset` may delete,
 // the host command that seeds them, and the URLs derived from leased ports. Hashing them made raising cold_start_seconds strand a