@klickd/core 4.0.1 → 4.0.3

package/dist/index.cjs

@@ -333,16 +333,696 @@ async function loadKlickd(input, options = {}) {
   return payload;
 }
 
+// src/schemas/klickd-payload-v4.schema.json
+var klickd_payload_v4_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://klickd.app/schemas/v4/klickd-payload.schema.json",
+  title: "klickd Payload v4 (Strict GA candidate, normative)",
+  description: "Strict JSON Schema for the .klickd v4 inner payload. This schema is the GA strict equivalent of the permissive klickd-payload-v4-preview.schema.json. Strict blocks correspond to RFC-001 (media_profile v1, Accepted) and RFC-002 v1 core (verification_gates, human_veto_policy, claim_sources v1, Accepted). Sections that remain Draft (RFC-002 v2-additive: contract_tests, success_criteria, reversibility, blast_radius, verification_artifacts, error_journal.rule_created; RFC-004 migration runtime) are accepted but left permissive so they can be tightened by a future strict schema bump without breaking GA writers. Top-level additionalProperties is TRUE to preserve unknown fields verbatim (SPEC.md \xA733.7 forward-compatibility invariant). Strict shape on frozen sub-objects uses additionalProperties: false locally. Does NOT supersede the permissive preview schema (klickd-payload-v4-preview.schema.json) \u2014 both coexist until the preview sunset announced separately.",
+  type: "object",
+  required: [
+    "payload_schema_version"
+  ],
+  additionalProperties: true,
+  properties: {
+    payload_schema_version: {
+      type: "string",
+      description: "Payload schema version. For GA strict files, the canonical value is '4.0'. The preview value '4.0.0-preview.1' is also accepted so a preview file already in the wild round-trips against the strict schema without forcing a rewrite. A future strict bump (4.1, etc.) MAY tighten this enum.",
+      enum: ["4.0", "4.0.0-preview.1"]
+    },
+    domain_schema_version: {
+      type: "string",
+      description: "Domain-specific schema version. Two accepted forms: (a) v3-style '{domain}-{major}.{minor}' (e.g. 'education-1.2'); (b) bare semver-ish '{major}.{minor}(.{patch})?' for domain-agnostic profiles (e.g. '1.0.0').",
+      pattern: "^([a-z][a-z0-9_-]*-\\d+\\.\\d+|\\d+\\.\\d+(\\.\\d+)?)$"
+    },
+    preview: {
+      type: "string",
+      description: "OPTIONAL preview marker. Present only on files written against a preview iteration (e.g. 'v4.0.0-preview.1'). Absent on GA strict files."
+    },
+    profile_kind: {
+      type: "string",
+      description: "Top-level discriminator for the profile shape. Reserved canonical values: 'learner', 'agent', 'team', 'robot', 'creator'. Custom strings are permitted (extension space). v3.x is implicitly 'learner'."
+    },
+    injection_target: {
+      type: "string",
+      enum: ["system_prompt", "user_message", "both"],
+      description: "Where to inject the .klickd context (carried over from v3.x \xA720.2)."
+    },
+    identity: {
+      type: "object",
+      description: "Persistent user identity attributes. Carried over from v3 SPEC \xA78; same strictness as v3 payload schema. All sub-fields are OPTIONAL.",
+      additionalProperties: true,
+      properties: {
+        name: { type: "string", maxLength: 256 },
+        display_name: { type: "string", maxLength: 256, description: "v4 GA preferred user-facing alias. Either 'name' or 'display_name' may be used; producers SHOULD pick one." },
+        language: { type: "string", description: "BCP 47 language tag." },
+        timezone: { type: "string", description: "IANA time zone identifier." },
+        communication_style: { type: "string" }
+      }
+    },
+    companion_identity: {
+      type: "object",
+      description: "Optional companion / co-agent persona. Same surface as v3.4 \xA727. Permissive.",
+      additionalProperties: true
+    },
+    context: {
+      type: "object",
+      description: "Operational session state. Carried over from v3 SPEC \xA79. Permissive (unevaluatedProperties policy of v3 retained).",
+      additionalProperties: true
+    },
+    knowledge: {
+      type: "object",
+      description: "Structured knowledge state. Carried over from v3 SPEC \xA710. Permissive.",
+      additionalProperties: true
+    },
+    memory: {
+      type: "array",
+      maxItems: 1e3,
+      description: "Structured conversation/event log. Same v3 \xA711 constraints retained.",
+      items: { type: "object", additionalProperties: true }
+    },
+    learning_goal: {
+      type: "object",
+      description: "User's stated learning / delivery goal. Same surface as v3 \xA727. Permissive.",
+      additionalProperties: true,
+      properties: {
+        type: { type: "string" },
+        deadline: { type: "string" },
+        stakes: { type: "string", enum: ["low", "medium", "high"] }
+      }
+    },
+    user_preferences: {
+      oneOf: [
+        { type: "string", maxLength: 32768 },
+        { type: "object", additionalProperties: true }
+      ],
+      description: "Canonical type is string (v3.5 \xA722.6). Object form retained for backward compatibility."
+    },
+    agent_instructions: {
+      type: "string",
+      maxLength: 32768,
+      description: "System-prompt injection string. Same v3 \xA77.2 contract."
+    },
+    onboarding_trigger: {
+      type: "string",
+      description: "Optional onboarding trigger (v3.4 \xA729b). Common values: 'on_new_agent', 'manual'."
+    },
+    ethics: {
+      type: "object",
+      description: "Ethical guard surface (v3.x). Permissive in this schema; safety / locked fields are governed by docs/spec/DEPRECATION_POLICY_V4.md \xA79.",
+      additionalProperties: true
+    },
+    media_profile: {
+      description: "RFC-001 v1 (Accepted): portable, hash-referenced media context. Strict on the v1 frozen surface (versioned + entries[]); a permissive 'summary' form (preview-era) is also accepted for round-trip compatibility. New modalities / fields land via additive RFC bumps.",
+      oneOf: [
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["version", "entries"],
+          properties: {
+            version: { type: "integer", const: 1, description: "media_profile schema version. v1 per RFC-001." },
+            entries: {
+              type: "array",
+              maxItems: 256,
+              items: { $ref: "#/$defs/mediaProfileEntry" }
+            }
+          }
+        },
+        {
+          type: "object",
+          description: "Permissive summary form (preview-era). Strict producers SHOULD migrate to the versioned + entries[] form. Kept for round-trip parity with vectors_v40_preview.json.",
+          additionalProperties: true,
+          not: { required: ["version", "entries"] }
+        },
+        {
+          type: "null"
+        }
+      ]
+    },
+    verification_gates: {
+      description: "RFC-002 v1 core (Accepted): user's preferred friction profile per action class. Two accepted shapes: (a) structured form (recommended) with version + gates[]; (b) flat map {action_class: level} for compactness (used by \xA733.5 minimal example and preview readers).",
+      oneOf: [
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["version", "gates"],
+          properties: {
+            version: { type: "integer", const: 1 },
+            user_default: { $ref: "#/$defs/gateLevel" },
+            gates: {
+              type: "array",
+              maxItems: 256,
+              items: { $ref: "#/$defs/gateEntry" }
+            }
+          }
+        },
+        {
+          type: "object",
+          description: "Flat map form: {action_class: gate_level}. Each value MUST be one of the five canonical levels.",
+          additionalProperties: { $ref: "#/$defs/gateLevel" }
+        }
+      ]
+    },
+    human_veto_policy: {
+      description: "RFC-002 v1 (Accepted): standing rules about when a human MUST be in the loop. Overrides any lower gate.",
+      type: ["object", "null"],
+      additionalProperties: false,
+      properties: {
+        applies_to: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 64,
+          description: "List of action classes for which a human veto is required."
+        },
+        second_party: {
+          type: ["string", "null"],
+          description: "Optional named second party who may unlock. null means owner-only."
+        },
+        min_level: {
+          $ref: "#/$defs/gateLevel",
+          description: "Floor gate level. The policy MUST NOT resolve below this level for any action class in 'applies_to'. RFC-002 v1 \xA74 #6 \u2014 human veto is sacred."
+        },
+        rationale: { type: "string", maxLength: 1024 }
+      }
+    },
+    claim_sources: {
+      description: "RFC-002 v1 (Accepted) + v2-additive (Draft). Strict on v1 fields ('prefer', 'require_citation_for'); 'records' and extended fields remain permissive (v2 still Draft).",
+      type: ["object", "null"],
+      additionalProperties: true,
+      properties: {
+        prefer: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 64,
+          description: "Ordered preference list. Each entry is a free-form source identifier; common values: 'user_supplied', 'tool:web_search', 'tool:doi_resolver'."
+        },
+        require_citation_for: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 64
+        },
+        records: {
+          type: "array",
+          description: "v2-additive (Draft). Permissive until promoted.",
+          items: { type: "object", additionalProperties: true }
+        }
+      }
+    },
+    risk_thresholds: {
+      description: "RFC-002 v1 (Accepted): numeric / categorical knobs. Permissive on inner shape \u2014 extension space.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    preflight_checks: {
+      description: "RFC-002 v1 (Accepted): small named checks to run before acting. Each entry is an object with at minimum 'name'.",
+      type: ["array", "null"],
+      items: { type: ["object", "string"], additionalProperties: true }
+    },
+    error_journal: {
+      description: "RFC-002 v1 (Accepted): append-only lessons learned. Permissive on entry shape ('rule_created' remains Draft in v2-additive).",
+      type: ["array", "null"],
+      items: { type: "object", additionalProperties: true }
+    },
+    verification_artifacts: {
+      description: "RFC-002 \xA78b.8 (Draft, v2-additive). Permissive: pointer ledger, not a payload sink. Accepted as null or array.",
+      type: ["array", "null"],
+      items: { type: "object", additionalProperties: true }
+    },
+    contract_tests: {
+      description: "RFC-002 v2-additive (Draft). Permissive.",
+      type: ["array", "null"],
+      items: { type: "object", additionalProperties: true }
+    },
+    success_criteria: {
+      description: "RFC-002 v2-additive (Draft). Permissive.",
+      type: ["object", "array", "null"],
+      additionalProperties: true
+    },
+    reversibility: {
+      description: "RFC-002 v2-additive (Draft). Permissive \u2014 typical shape is {action_class: enum<reversible|costly_to_reverse|irreversible|low|none|high>} but enums are not yet frozen.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    blast_radius: {
+      description: "RFC-002 v2-additive (Draft). Permissive.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    migration: {
+      description: "RFC-004 (Draft): optional migration metadata block. Audit-only \u2014 no migration tooling ships with the strict schema. Strict on v1 frozen fields; extension fields permitted.",
+      type: ["object", "null"],
+      additionalProperties: true,
+      properties: {
+        source_version: { type: "string" },
+        migrated_at: {
+          type: "string",
+          pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
+        },
+        migration_report_ref: { type: "string" },
+        backup_ref: { type: "string" }
+      }
+    },
+    context_cost: {
+      description: "Research/benchmark track (benchmarks/context_cost/RFC.md). No spec semantics depend on this field. Permissive.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    gaming_profile: {
+      description: "R4-P1-4 gaming.klickd baseline (preview, registry-based). NOT a v4 MUST. Accepted as a registry-defined optional profile; permissive structure.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    deprecated_fields: {
+      description: "OPTIONAL informational block defined by docs/spec/DEPRECATION_POLICY_V4.md \xA76. Lists fields the producer has emitted as 'deprecated' status. Readers that don't understand it MUST silently ignore (\xA733.7).",
+      type: ["array", "null"],
+      items: {
+        type: "object",
+        additionalProperties: true,
+        required: ["name"],
+        properties: {
+          name: { type: "string" },
+          since: { type: "string" },
+          replacement: { type: ["string", "null"] },
+          removal_target: { type: ["string", "null"] }
+        }
+      }
+    },
+    _example_metadata: {
+      description: "Optional non-normative block used by repository examples (see examples/v4/personas/README.md). Carries 'persona', 'non_normative', 'contains_real_pii', 'contains_secrets', etc. A reader MUST NOT use this block as a trust signal.",
+      type: "object",
+      additionalProperties: true
+    }
+  },
+  $defs: {
+    gateLevel: {
+      type: "string",
+      enum: ["silent", "warn", "confirm", "block", "require-owner"],
+      description: "RFC-002 v1 \xA76 \u2014 fixed enum of five gate levels. No new levels are added in GA."
+    },
+    gateEntry: {
+      type: "object",
+      additionalProperties: false,
+      required: ["action_class", "level"],
+      properties: {
+        id: { type: "string", maxLength: 128 },
+        action_class: { type: "string", maxLength: 128 },
+        level: { $ref: "#/$defs/gateLevel" },
+        reason: { type: "string", maxLength: 1024 }
+      }
+    },
+    mediaProfileEntry: {
+      type: "object",
+      additionalProperties: true,
+      required: ["id", "modality", "hash"],
+      description: "RFC-001 v1 entry. Strict on v1 frozen fields (id, modality, hash). Additional metadata (consent, producer, etc.) is permitted as extension surface.",
+      properties: {
+        id: { type: "string", maxLength: 128 },
+        modality: {
+          type: "string",
+          enum: ["voice", "image", "document", "embedding"],
+          description: "RFC-001 v1 \xA74 #3 \u2014 closed enum at v1. Custom modalities live under 'x_*' namespaces (outside this entry)."
+        },
+        label: { type: "string", maxLength: 256 },
+        language: { type: "string" },
+        uri: { type: "string", description: "May be file://, https://, ipfs://, cas://<hash>, or a relative path. Reader chooses how to resolve." },
+        media_type: { type: "string" },
+        byte_size: { type: "integer", minimum: 0 },
+        duration_ms: { type: "integer", minimum: 0 },
+        bytes_b64: {
+          type: "string",
+          contentEncoding: "base64",
+          description: "Inline base64 PERMITTED ONLY for entries \u2264 16 KiB total (RFC-001 v1 \xA74 #1). Strict enforcement of the 16 KiB cap is not expressible in JSON Schema and is enforced by reader-side logic."
+        },
+        hash: {
+          type: "object",
+          additionalProperties: false,
+          required: ["algo", "value"],
+          properties: {
+            algo: { type: "string", const: "blake3", description: "RFC-001 v1 \xA74 #2 \u2014 one hash, one algorithm: BLAKE3." },
+            value: { type: "string", description: "Hash value, encoding per RFC-001 (base64 or hex-prefixed). Strict format enforcement is reader-side." }
+          }
+        },
+        producer: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            kind: { type: "string" },
+            device: { type: "string" }
+          }
+        },
+        consent: {
+          type: "object",
+          additionalProperties: true,
+          description: "RFC-001 v1 \xA74 #5 \u2014 consent is per-entry, not per-file.",
+          properties: {
+            purposes: {
+              type: "array",
+              items: { type: "string" },
+              maxItems: 64
+            },
+            expires_at: { type: "string" },
+            revocable: { type: "boolean" }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/schemas/klickd-payload-v4-preview.schema.json
+var klickd_payload_v4_preview_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://klickd.app/schemas/v4-preview/klickd-payload.schema.json",
+  title: "klickd Payload v4 Preview (PERMISSIVE, NON-NORMATIVE)",
+  description: "PREVIEW schema for the .klickd v4 inner payload, targeting v4.0.0-preview.1. This schema is INTENTIONALLY PERMISSIVE: it accepts and preserves draft v4 structures (media_profile, verification_gates, human_veto_policy, claim_sources, verification_artifacts, migration, context_cost, profile_kind) without performing strict validation. additionalProperties is true at every level so that unknown fields round-trip verbatim. This schema MUST NOT be used to reject a file that is otherwise a valid v3.5.1 file. The normative schemas remain klickd-envelope-v3.schema.json and klickd-payload-v3.schema.json. See SPEC.md \xA733 and docs/rfcs/ for the design source.",
+  type: "object",
+  additionalProperties: true,
+  properties: {
+    preview: {
+      type: "string",
+      description: "Marks a file as belonging to a specific preview iteration. Recommended value for files written against this schema: 'v4.0.0-preview.1'. Absent in v3.x files."
+    },
+    payload_schema_version: {
+      type: "string",
+      description: "Payload schema version. PERMISSIVE in this preview: any string is accepted. A future strict v4 schema MAY pin this to a concrete value."
+    },
+    domain_schema_version: {
+      type: "string",
+      description: "Domain-specific schema version (e.g. 'education-1.2'). PERMISSIVE in this preview."
+    },
+    profile_kind: {
+      type: "string",
+      description: "Top-level discriminator for the profile shape. Common values: 'learner', 'agent', 'team', 'robot'. v3.x is implicitly 'learner'; the preview makes this explicit and extensible. Custom strings are permitted."
+    },
+    media_profile: {
+      description: "RFC-001: portable, hash-referenced media context. Bytes live outside the .klickd file by default; the payload carries metadata, hashes, and (optionally) inline base64 below a documented threshold. PERMISSIVE: structure is not enforced here.",
+      type: ["object", "array", "null"],
+      additionalProperties: true
+    },
+    verification_gates: {
+      description: "RFC-002 v1: user's preferred friction profile, mapping action class to gate level (silent / warn / confirm / block / require-owner). PERMISSIVE: not enforced here.",
+      type: ["object", "array", "null"],
+      additionalProperties: true
+    },
+    human_veto_policy: {
+      description: "RFC-002 v1: standing rules about when a human MUST be in the loop, regardless of agent confidence. Overrides any lower gate. PERMISSIVE: not enforced here.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    claim_sources: {
+      description: "RFC-002 v1 + v2-additive: declarative preferences for where to ground factual claims, and records of what was actually used. PERMISSIVE: not enforced here.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    verification_artifacts: {
+      description: "RFC-002 \xA78b.8: pointer ledger of outputs already produced by expensive verification commands (test suites, builds, web fetches, DOI resolutions). MUST be a pointer ledger, not a payload sink. PERMISSIVE: structure is not enforced here.",
+      type: ["array", "null"]
+    },
+    error_journal: {
+      description: "RFC-002 v1: append-only lessons learned that should influence future gate evaluation. PERMISSIVE: not enforced here.",
+      type: ["array", "null"]
+    },
+    risk_thresholds: {
+      description: "RFC-002 v1: numeric / categorical knobs (e.g. public_reach, financial_amount_eur_max_silent). PERMISSIVE.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    preflight_checks: {
+      description: "RFC-002 v1: small, named checks an agent SHOULD run before acting on certain classes. PERMISSIVE.",
+      type: ["array", "null"]
+    },
+    contract_tests: {
+      description: "RFC-002 v2-additive: machine-checkable contract tests bound to action classes. PERMISSIVE.",
+      type: ["array", "null"]
+    },
+    success_criteria: {
+      description: "RFC-002 v2-additive: declarative success criteria per action class. PERMISSIVE.",
+      type: ["object", "array", "null"],
+      additionalProperties: true
+    },
+    reversibility: {
+      description: "RFC-002 v2-additive: declared reversibility for action classes. PERMISSIVE.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    blast_radius: {
+      description: "RFC-002 v2-additive: declared blast radius for action classes. PERMISSIVE.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    migration: {
+      description: "RFC-004: optional migration metadata block. Audit-only in this preview \u2014 no migration tooling ships with v4.0.0-preview.1. PERMISSIVE.",
+      type: ["object", "null"],
+      additionalProperties: true,
+      properties: {
+        source_version: { type: "string" },
+        migrated_at: { type: "string" },
+        migration_report_ref: { type: "string" },
+        backup_ref: { type: "string" }
+      }
+    },
+    context_cost: {
+      description: "Research/benchmark track (benchmarks/context_cost/RFC.md): optional fields recording measured 'repeated context waste' for this profile. No normative semantics depend on this field. PERMISSIVE.",
+      type: ["object", "null"],
+      additionalProperties: true
+    }
+  }
+};
+
+// src/schemas/klickd-v4.schema.json
+var klickd_v4_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://klickd.app/schema/v4/klickd.schema.json",
+  title: "klickd v4 \u2014 Unified (Strict GA candidate, normative)",
+  description: "Strict unified JSON Schema for a .klickd v4 document (envelope + optional inline payload). This schema is the GA strict equivalent of the permissive klickd-v4-preview.schema.json. It validates the envelope shape strictly (mirroring the v3 envelope contract \u2014 Argon2id + AES-256-GCM is unchanged in v4 per SPEC.md \xA733.10 #2) and, for unencrypted files, validates the inline payload against the strict v4 payload schema (klickd-payload-v4.schema.json). Top-level additionalProperties is TRUE to preserve unknown fields verbatim (SPEC.md \xA733.7 forward-compatibility invariant). Does NOT supersede the permissive preview schema (klickd-v4-preview.schema.json) \u2014 both coexist.",
+  type: "object",
+  additionalProperties: true,
+  required: ["klickd_version", "created_at", "encrypted"],
+  properties: {
+    klickd_version: {
+      type: "string",
+      description: "Wire / envelope version. Strict v4 GA producers SHOULD emit '4.0'. v3.x values are also accepted because the v3 envelope contract is unchanged (\xA733.10 #2) and a v3.x file remains readable by a v4 reader.",
+      pattern: "^(3|4)\\.\\d+(\\.[0-9A-Za-z-.]+)?$"
+    },
+    preview: {
+      type: "string",
+      description: "OPTIONAL preview marker. Absent on GA strict files. If present, this file was written against a preview iteration (e.g. 'v4.0.0-preview.1')."
+    },
+    created_at: {
+      type: "string",
+      description: "RFC 3339 UTC timestamp of file creation. Z-suffix only, no fractional seconds (matches v3 envelope strict contract).",
+      pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    encrypted: {
+      type: "boolean"
+    },
+    domain: {
+      type: "string",
+      minLength: 1,
+      description: "Semantic category. Registered values follow v3 (education, work, finance, legal, creative, health, research, robotics, gaming, creator). Custom non-empty strings are permitted."
+    },
+    profile_kind: {
+      type: "string",
+      description: "Top-level discriminator for the profile shape. Reserved canonical values: 'learner', 'agent', 'team', 'robot', 'creator'."
+    },
+    domain_schema_version: {
+      type: "string",
+      pattern: "^([a-z][a-z0-9_-]*-\\d+\\.\\d+|\\d+\\.\\d+(\\.\\d+)?)$"
+    },
+    kdf: {
+      type: "object",
+      description: "Structured KDF block \u2014 same contract as envelope-v3 \xA715.",
+      required: ["name", "params", "salt"],
+      additionalProperties: false,
+      properties: {
+        name: { type: "string", enum: ["argon2id", "pbkdf2-sha256"] },
+        params: {
+          oneOf: [
+            {
+              type: "object",
+              required: ["m", "t", "p"],
+              additionalProperties: false,
+              properties: {
+                m: { type: "integer", minimum: 65536 },
+                t: { type: "integer", minimum: 1 },
+                p: { type: "integer", minimum: 1 }
+              }
+            },
+            {
+              type: "object",
+              required: ["iterations"],
+              additionalProperties: false,
+              properties: {
+                iterations: { type: "integer", minimum: 6e5 }
+              }
+            }
+          ]
+        },
+        salt: { type: "string" }
+      }
+    },
+    cipher: {
+      type: "object",
+      description: "Structured cipher block \u2014 same contract as envelope-v3 \xA716. v4 does not introduce a new cipher.",
+      required: ["name", "iv"],
+      additionalProperties: false,
+      properties: {
+        name: { type: "string", const: "AES-256-GCM" },
+        iv: { type: "string" }
+      }
+    },
+    ciphertext: {
+      type: "string",
+      description: "AES-256-GCM ciphertext (base64 padded). Required when encrypted=true."
+    },
+    iv: {
+      type: "string",
+      description: "Legacy top-level IV mirror, retained for v3.0 round-trip parity. New producers SHOULD place IV inside the structured cipher block."
+    },
+    kdf_salt: {
+      type: "string",
+      description: "Legacy top-level salt mirror, retained for v3.0 round-trip parity."
+    },
+    payload_schema_version: {
+      type: "string",
+      description: "Payload schema version when the payload is inline (encrypted=false). Strict v4 GA value: '4.0'. Preview '4.0.0-preview.1' accepted for round-trip.",
+      enum: ["4.0", "4.0.0-preview.1"]
+    },
+    media_profile: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/media_profile" },
+    verification_gates: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/verification_gates" },
+    human_veto_policy: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/human_veto_policy" },
+    claim_sources: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/claim_sources" },
+    verification_artifacts: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/verification_artifacts" },
+    contract_tests: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/contract_tests" },
+    success_criteria: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/success_criteria" },
+    reversibility: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/reversibility" },
+    blast_radius: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/blast_radius" },
+    risk_thresholds: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/risk_thresholds" },
+    preflight_checks: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/preflight_checks" },
+    error_journal: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/error_journal" },
+    migration: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/migration" },
+    context_cost: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/context_cost" },
+    gaming_profile: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/gaming_profile" },
+    deprecated_fields: { $ref: "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/deprecated_fields" }
+  },
+  allOf: [
+    {
+      if: {
+        type: "object",
+        properties: { encrypted: { const: true } },
+        required: ["encrypted"]
+      },
+      then: {
+        required: ["kdf", "cipher", "ciphertext"],
+        description: "Encrypted v4 file MUST carry kdf + cipher + ciphertext (envelope-v3 contract retained)."
+      }
+    }
+  ]
+};
+
+// src/schemas/klickd-v4-preview.schema.json
+var klickd_v4_preview_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://klickd.app/schema/v4-preview/klickd.schema.json",
+  title: "klickd v4 Preview \u2014 Unified (PERMISSIVE, NON-NORMATIVE)",
+  description: "PREVIEW unified schema for .klickd v4, targeting v4.0.0-preview.1. This schema is INTENTIONALLY PERMISSIVE: it validates the top-level shape of a v4-preview file (envelope + optional preview hooks) without enforcing strict v4 semantics. additionalProperties is true so unknown fields round-trip verbatim. Use this for single-pass acceptance of draft v4 documents. For pre-/post-decrypt validation, see schemas/klickd-payload-v4-preview.schema.json. The normative production schemas remain schema/klickd-v3.4.schema.json (unified) and schemas/klickd-envelope-v3.schema.json + schemas/klickd-payload-v3.schema.json (split). See SPEC.md \xA733.",
+  type: "object",
+  additionalProperties: true,
+  required: ["klickd_version", "created_at", "encrypted"],
+  properties: {
+    klickd_version: {
+      type: "string",
+      description: "Wire / envelope version. PERMISSIVE in this preview \u2014 any MAJOR.MINOR string is accepted. Preview producers SHOULD emit '4.0' and pair it with a 'preview' field. v3.x producers MUST continue to emit '3.x' and MUST NOT emit a 'preview' field.",
+      pattern: "^\\d+\\.\\d+(\\.[0-9A-Za-z-.]+)?$"
+    },
+    preview: {
+      type: "string",
+      description: "Marks a file as belonging to a specific preview iteration. Recommended value for files written against this schema: 'v4.0.0-preview.1'. Absent in v3.x and in a future GA v4.0."
+    },
+    created_at: {
+      type: "string",
+      description: "RFC 3339 UTC timestamp of file creation. Same contract as v3.x.",
+      pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      format: "date-time"
+    },
+    encrypted: {
+      type: "boolean",
+      description: "Whether the payload is AES-256-GCM encrypted. Envelope cryptography is unchanged from v3.x in this preview."
+    },
+    domain: {
+      type: "string",
+      description: "Semantic category of the context. Same surface as v3.x; custom strings remain permitted."
+    },
+    profile_kind: {
+      type: "string",
+      description: "Top-level discriminator for the profile shape. Common values: 'learner', 'agent', 'team', 'robot'. Custom strings are permitted."
+    },
+    ciphertext: {
+      type: "string",
+      description: "AES-256-GCM ciphertext when encrypted is true. Same contract as v3.x.",
+      contentEncoding: "base64"
+    },
+    iv: {
+      type: "string",
+      contentEncoding: "base64"
+    },
+    kdf_salt: {
+      type: "string",
+      contentEncoding: "base64"
+    },
+    kdf: {
+      type: "object",
+      additionalProperties: true,
+      description: "Structured KDF block as in envelope-v3. Unchanged in this preview."
+    },
+    cipher: {
+      type: "object",
+      additionalProperties: true,
+      description: "Structured cipher block as in envelope-v3. Unchanged in this preview."
+    },
+    media_profile: {
+      description: "RFC-001 (preview hook). PERMISSIVE \u2014 see schemas/klickd-payload-v4-preview.schema.json.",
+      type: ["object", "array", "null"],
+      additionalProperties: true
+    },
+    verification_gates: {
+      description: "RFC-002 (preview hook). PERMISSIVE.",
+      type: ["object", "array", "null"],
+      additionalProperties: true
+    },
+    human_veto_policy: {
+      description: "RFC-002 (preview hook). PERMISSIVE.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    claim_sources: {
+      description: "RFC-002 (preview hook). PERMISSIVE.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    verification_artifacts: {
+      description: "RFC-002 \xA78b.8 (preview hook). PERMISSIVE \u2014 pointer ledger, not a payload sink.",
+      type: ["array", "null"]
+    },
+    migration: {
+      description: "RFC-004 (preview hook). Audit-only in v4.0.0-preview.1.",
+      type: ["object", "null"],
+      additionalProperties: true
+    },
+    context_cost: {
+      description: "Research/benchmark track (preview hook). No normative semantics.",
+      type: ["object", "null"],
+      additionalProperties: true
+    }
+  }
+};
+
 // src/validate.ts
-var import_klickd_payload_v4_schema = __toESM(require("./klickd-payload-v4.schema-7UPTEJOY.json"), 1);
-var import_klickd_payload_v4_preview_schema = __toESM(require("./klickd-payload-v4-preview.schema-W7RY72VP.json"), 1);
-var import_klickd_v4_schema = __toESM(require("./klickd-v4.schema-ZZGRYTLY.json"), 1);
-var import_klickd_v4_preview_schema = __toESM(require("./klickd-v4-preview.schema-QHITWMK6.json"), 1);
 var SCHEMAS = {
-  "payload-strict": import_klickd_payload_v4_schema.default,
-  "payload-preview": import_klickd_payload_v4_preview_schema.default,
-  "unified-strict": import_klickd_v4_schema.default,
-  "unified-preview": import_klickd_v4_preview_schema.default
+  "payload-strict": klickd_payload_v4_schema_default,
+  "payload-preview": klickd_payload_v4_preview_schema_default,
+  "unified-strict": klickd_v4_schema_default,
+  "unified-preview": klickd_v4_preview_schema_default
 };
 function getBundledSchema(key) {
   const s = SCHEMAS[key];
@@ -586,9 +1266,30 @@ var import_node_url = require("url");
 var import_node_path = require("path");
 var import_node_fs = require("fs");
 var import_meta = {};
+function moduleDir() {
+  if (typeof __dirname !== "undefined") {
+    return __dirname;
+  }
+  const metaUrl = import_meta?.url;
+  if (typeof metaUrl === "string" && metaUrl.length > 0) {
+    return (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(metaUrl));
+  }
+  throw new Error(
+    "@klickd/core: unable to resolve module directory for starter-skills"
+  );
+}
 function starterSkillsDir() {
-  const here = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
-  return (0, import_node_path.join)(here, "..", "starter-skills");
+  const here = moduleDir();
+  const candidates = [
+    (0, import_node_path.join)(here, "..", "starter-skills"),
+    (0, import_node_path.join)(here, "starter-skills")
+  ];
+  for (const candidate of candidates) {
+    if ((0, import_node_fs.existsSync)(candidate)) {
+      return candidate;
+    }
+  }
+  return candidates[0];
 }
 function getStarterSkillsDir() {
   return starterSkillsDir();