akm-cli 0.9.0-beta.46 → 0.9.0-beta.48

package/dist/assets/wiki/ingest-workflow-template.md

@@ -6,20 +6,27 @@ Schema: {{SCHEMA_PATH}}
 Follow these steps. akm commands handle the invariants; use your native
 Read/Write/Edit tools for page edits.
 
+This workflow is for ingesting sources that are ALREADY present under
+`{{WIKI_DIR}}/raw/`. Do not ask the user for a source unless the raw queue is
+empty and the caller explicitly asked for interactive ingest.
+
 1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
    kinds, contradiction policy, and any wiki-specific conventions. Do not
    skip this step even on familiar wikis — the schema may have changed.
 
-2. **File the source under `raw/`.**
+2. **Discover the pending raw queue.**
    ```sh
-   akm wiki stash {{WIKI_NAME}} <path-or-url-to-source>
-   # or: cat <source> | akm wiki stash {{WIKI_NAME}} -
+   akm wiki lint {{WIKI_NAME}}
    ```
-   Returns `{ slug, path, ref }`. The raw copy is immutable — never edit it.
+   Focus on `uncited-raw` findings: those raw files exist under `raw/` but are
+   not yet cited by any authored page. Treat each `uncited-raw` finding as a
+   pending ingest item. If there are no `uncited-raw` findings, exit cleanly
+   after a final `akm index` + `akm wiki lint {{WIKI_NAME}}` verification.
 
-3. **Find related existing pages.**
+3. **For each pending raw file, read the source and find related pages.**
+   Open the raw file directly from `{{WIKI_DIR}}/raw/`, then search:
    ```sh
-   akm wiki search {{WIKI_NAME}} "<key terms from the source>"
+   akm wiki search {{WIKI_NAME}} "<key terms from the raw source>"
    ```
    Read the top hits with `akm show wiki:{{WIKI_NAME}}/<page>`. Use
    `akm show wiki:{{WIKI_NAME}}/<page> toc` for large pages.
@@ -39,8 +46,8 @@ Read/Write/Edit tools for page edits.
 6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
    page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
 
-7. **Append to `log.md`.** One entry per ingest: date, source slug, one-line
-   summary, refs to created/edited pages. Newest at the top.
+7. **Append to `log.md`.** One entry per ingested raw source: date, raw slug,
+   one-line summary, refs to created/edited pages. Newest at the top.
 
 8. **Regenerate the index + verify.**
    ```sh
@@ -50,5 +57,5 @@ Read/Write/Edit tools for page edits.
    Resolve any lint findings before calling the ingest done.
 
 That's it. `akm` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, unique slugs, ref validation, index
-regeneration, structural lint).
+the invariants (raw immutability, ref validation, index regeneration,
+structural lint).

package/dist/core/config/config-schema.js

@@ -22,8 +22,14 @@
  * - Two exceptions (hard-rejected): openviking source type and legacy
  *   `stashes[]` key. Both have explicit migration paths; silently dropping
  *   would mask user data loss.
- * - `.strict()` walls still gate `registries[]`, `sources[]`, `profiles.*`
- *   sub-shapes so typos in those structured records are caught (#462).
+ * - UNKNOWN-KEY POLICY: object schemas use passthrough (unknown keys are
+ *   preserved and ignored, NOT rejected). akm runs across multiple installed
+ *   versions sharing one config.json; a newer version writes keys an older
+ *   version's schema doesn't know yet, so hard-rejecting unknown keys turned
+ *   benign version skew into `INVALID_CONFIG_FILE` failures. Known keys are
+ *   still type-checked; passthrough preserves unknown keys across a
+ *   load→save round trip so an older reader never strips a newer writer's
+ *   settings. (Replaced the prior strict-mode object walls.)
  * - `defaultWriteTarget` resolution and similar cross-field invariants are
  *   enforced at save time via `superRefine` on the top-level schema.
  */
@@ -50,7 +56,7 @@ const LlmCapabilitiesSchema = z
     .object({
     structuredOutput: z.boolean().optional(),
 })
-    .strict();
+    .passthrough();
 /**
  * Connection config used for both top-level `llm` (after migration) and
  * `profiles.llm[*]`. `model` is required at schema level — partial entries
@@ -75,15 +81,15 @@ export const LlmConnectionConfigSchema = z
     judgeModel: z.string().min(1).optional(),
     enableThinking: z.boolean().optional(),
 })
-    .strict();
+    .passthrough();
 export const LlmProfileConfigSchema = LlmConnectionConfigSchema.extend({
     supportsJsonSchema: z.boolean().optional(),
-}).strict();
+}).passthrough();
 const EmbeddingOllamaOptionsSchema = z
     .object({
     num_ctx: positiveInt.optional(),
 })
-    .strict();
+    .passthrough();
 /**
  * Embedding connection config. Both `endpoint` and `model` are optional:
  *   - Remote: provide `endpoint` (http/https URL) + `model`.
@@ -107,7 +113,7 @@ export const EmbeddingConnectionConfigSchema = z
     contextLength: positiveInt.optional(),
     ollamaOptions: EmbeddingOllamaOptionsSchema.optional(),
 })
-    .strict();
+    .passthrough();
 // ── Agent profiles ──────────────────────────────────────────────────────────
 // Derives from the canonical VALID_HARNESS_IDS (#565) so the Zod gate cannot
 // drift from the TS union / parse check / setup detection.
@@ -120,7 +126,7 @@ export const AgentProfileConfigSchema = z
     workspace: z.string().min(1).optional(),
     model: z.string().min(1).optional(),
 })
-    .strict();
+    .passthrough();
 // ── Improve profile / process ──────────────────────────────────────────────
 export const ImproveProcessConfigSchema = z
     .object({
@@ -151,7 +157,7 @@ export const ImproveProcessConfigSchema = z
         // with care — cost is O(n²).
         cosineCandidateLimit: z.number().int().positive().optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
     // Consolidate process: judged-state cache (#581). When enabled, a memory
     // whose current content hash equals its cached judged hash is SKIPPED from
@@ -160,9 +166,9 @@ export const ImproveProcessConfigSchema = z
     // time-window slice. Default OFF — when absent the consolidate pass behaves
     // byte-identically to today (the incrementalSince path is unaffected). Only
     // meaningful on the `consolidate` process.
-    judgedCache: z.object({ enabled: z.boolean().optional() }).strict().optional(),
-    qualityGate: z.object({ enabled: z.boolean().optional() }).strict().optional(),
-    contradictionDetection: z.object({ enabled: z.boolean().optional() }).strict().optional(),
+    judgedCache: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
+    qualityGate: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
+    contradictionDetection: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
     // Extract process config (only meaningful for extract process)
     defaultSince: z.string().min(1).optional(),
     maxTotalChars: positiveInt.optional(),
@@ -236,7 +242,7 @@ export const ImproveProcessConfigSchema = z
         // Demotion factor: multiply retrievalSalience by this when stale (default 0.5).
         demotionFactor: z.number().min(0).max(1).optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
     // WS-3b: Schema-similarity gate (step 0b). At intake, if a new candidate's
     // body embedding is within epsilon of an existing derived-layer lesson/knowledge
@@ -253,7 +259,7 @@ export const ImproveProcessConfigSchema = z
         // to pass the quality gate and create redundant stash entries.
         confidencePenalty: z.number().min(0).max(1).optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
     // WS-3b: Hot-probation intake buffer (step 0c, #604). New system-generated
     // extractions enter captureMode: hot-probation and spend ONE consolidation
@@ -263,7 +269,7 @@ export const ImproveProcessConfigSchema = z
         .object({
         enabled: z.boolean().optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
     // WS-3b: Anti-collapse guards (step 8). Prevents the consolidation pipeline
     // from collapsing too aggressively and losing diversity.
@@ -278,7 +284,7 @@ export const ImproveProcessConfigSchema = z
         lexicalDiversityCheck: z.boolean().optional(),
         randomClusterFraction: z.number().min(0).max(1).optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
     // WS-3b: CLS (Complementary Learning System) interleaving (step 9).
     // distill/memoryInference prompts include embedding-retrieved existing adjacent
@@ -290,7 +296,7 @@ export const ImproveProcessConfigSchema = z
         // Number of adjacent lessons/knowledge to include in prompts (default 3).
         adjacentCount: z.number().int().min(1).optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
     // WS-3b: Distill→source fidelity check (step 10). After a distill proposal,
     // check it against its cited source memories; a contradiction flag forces
@@ -299,7 +305,7 @@ export const ImproveProcessConfigSchema = z
         .object({
         enabled: z.boolean().optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
     // #609 — recombine process: minimum related-memory cluster size before an
     // LLM generalization call. Default 3. Only meaningful on `recombine`.
@@ -342,7 +348,7 @@ export const ImproveProcessConfigSchema = z
     // enabled, proposals classified as "low-value" by the deterministic noise
     // gate are deferred. DEFAULT OFF (absent / { enabled: false } = pre-#639
     // byte-identical behaviour). Only meaningful on the `reflect` process.
-    lowValueFilter: z.object({ enabled: z.boolean().optional() }).strict().optional(),
+    lowValueFilter: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
     // #641 — procedural-aware floor for the `extract` process triage gate.
     // When true, a session must have markers>=1 OR editCommit>=0.5 to pass, even
     // if score>=minScore. DEFAULT OFF (absent/false = pre-#641 byte-identical).
@@ -360,10 +366,10 @@ export const ImproveProcessConfigSchema = z
         profile: z.string().min(1).optional(),
         timeoutMs: z.union([positiveInt, z.null()]).optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
 })
-    .strict();
+    .passthrough();
 const ImproveProfileProcessesSchema = z
     .object({
     reflect: ImproveProcessConfigSchema.optional(),
@@ -380,37 +386,17 @@ const ImproveProfileProcessesSchema = z
     .passthrough()
     .superRefine((val, ctx) => {
     // 0.8.0 removed the duplicated `feedbackDistillation` process key — it was
-    // a thin wrapper around `processes.distill.enabled`. Single source of truth.
-    const raw = val;
-    if ("feedbackDistillation" in raw) {
+    // a thin wrapper around `processes.distill.enabled`. Keep the migration
+    // hint so a stale config gets an actionable message rather than silently
+    // doing nothing. All OTHER unknown process keys are tolerated (passthrough)
+    // — see the unknown-key policy in this file's header. Hard-rejecting them
+    // turned benign cross-version skew into INVALID_CONFIG_FILE failures.
+    if ("feedbackDistillation" in val) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             message: "feedbackDistillation was removed in 0.8.0 — use processes.distill.enabled instead. " +
                 "It now controls both the orchestration gate and the LLM-call gate.",
         });
-        return;
-    }
-    const allowed = new Set([
-        "reflect",
-        "distill",
-        "consolidate",
-        "memoryInference",
-        "graphExtraction",
-        "validation",
-        "extract",
-        "triage",
-        "proactiveMaintenance",
-        "recombine",
-        "procedural",
-    ]);
-    for (const k of Object.keys(raw)) {
-        if (!allowed.has(k)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.unrecognized_keys,
-                keys: [k],
-                message: `Unrecognized improve process key: "${k}".`,
-            });
-        }
     }
 });
 export const ImproveProfileConfigSchema = z
@@ -435,10 +421,10 @@ export const ImproveProfileConfigSchema = z
         push: z.boolean().optional(),
         message: z.string().min(1).optional(),
     })
-        .strict()
+        .passthrough()
         .optional(),
 })
-    .strict();
+    .passthrough();
 // ── Profiles / defaults ────────────────────────────────────────────────────
 export const ProfilesSchema = z
     .object({
@@ -446,14 +432,14 @@ export const ProfilesSchema = z
     agent: z.record(z.string(), AgentProfileConfigSchema).optional(),
     improve: z.record(z.string(), ImproveProfileConfigSchema).optional(),
 })
-    .strict();
+    .passthrough();
 export const DefaultsSchema = z
     .object({
     llm: z.string().min(1).optional(),
     agent: z.string().min(1).optional(),
     improve: z.string().min(1).optional(),
 })
-    .strict();
+    .passthrough();
 // ── Sources / registries / installed ────────────────────────────────────────
 const SourceConfigEntryOptionsSchema = z
     .object({
@@ -477,7 +463,7 @@ export const SourceConfigEntrySchema = z
     options: SourceConfigEntryOptionsSchema.optional(),
     wikiName: z.string().min(1).optional(),
 })
-    .strict()
+    .passthrough()
     .superRefine((entry, ctx) => {
     if (entry.writable === true && (entry.type === "website" || entry.type === "npm")) {
         ctx.addIssue({
@@ -496,7 +482,7 @@ export const RegistryConfigEntrySchema = z
     provider: z.string().min(1).optional(),
     options: z.record(z.unknown()).optional(),
 })
-    .strict();
+    .passthrough();
 const KitSourceSchema = z.enum(["filesystem", "git", "npm", "github", "website", "local"]);
 export const InstalledStashEntrySchema = z
     .object({
@@ -512,7 +498,7 @@ export const InstalledStashEntrySchema = z
     resolvedRevision: z.string().min(1).optional(),
     wikiName: z.string().min(1).optional(),
 })
-    .strict()
+    .passthrough()
     .superRefine((entry, ctx) => {
     if (entry.writable === true && entry.source !== "git" && entry.source !== "filesystem") {
         ctx.addIssue({
@@ -527,7 +513,7 @@ export const OutputConfigSchema = z
     format: z.enum(["json", "yaml", "text"]).optional(),
     detail: z.enum(["brief", "normal", "full"]).optional(),
 })
-    .strict();
+    .passthrough();
 // ── Search ──────────────────────────────────────────────────────────────────
 const SearchGraphBoostSchema = z
     .object({
@@ -541,29 +527,29 @@ const SearchGraphBoostSchema = z
     /** Range [0, 1]; values > 1 hard-error (no silent clamp). */
     confidenceWeight: z.number().finite().min(0).max(1).default(0.2).optional(),
 })
-    .strict();
+    .passthrough();
 export const SearchConfigSchema = z
     .object({
     minScore: nonNegativeNumber.optional(),
     defaultExcludeTypes: z.array(nonEmptyString).optional(),
-    curateRerank: z.object({ enabled: z.boolean().optional() }).strict().optional(),
+    curateRerank: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
     graphBoost: SearchGraphBoostSchema.optional(),
 })
-    .strict();
+    .passthrough();
 // ── Feedback ────────────────────────────────────────────────────────────────
 export const FeedbackConfigSchema = z
     .object({
     requireReason: z.boolean().optional(),
     allowedFailureModes: z.array(nonEmptyString).optional(),
 })
-    .strict();
+    .passthrough();
 // ── Improve top-level (utility decay, event retention) ─────────────────────
 const ImproveUtilityDecaySchema = z
     .object({
     halfLifeDays: z.number().finite().min(0.1).optional(),
     feedbackStabilityBoost: z.number().finite().min(1).optional(),
 })
-    .strict();
+    .passthrough();
 // #612 / WS-4 — auto-accept gate calibration + bounded, opt-in per-phase
 // threshold auto-tune. DEFAULT OFF: when absent (or `autoTune: false`) no
 // tuning occurs, so the gate behaves byte-identically to today.
@@ -586,7 +572,7 @@ const ImproveCalibrationSchema = z
     /** Target realized accept rate in [0, 1]. Default 0.9. */
     targetAcceptRate: z.number().finite().min(0).max(1).optional(),
 })
-    .strict();
+    .passthrough();
 // WS-4 — exploration budget: a fixed fraction of proposals accepted per run
 // regardless of confidence. DEFAULT OFF.
 const ImproveExplorationSchema = z
@@ -602,7 +588,7 @@ const ImproveExplorationSchema = z
      */
     budgetFraction: z.number().finite().min(0).max(1).optional(),
 })
-    .strict();
+    .passthrough();
 const ImproveSalienceSchema = z
     .object({
     /**
@@ -624,7 +610,7 @@ const ImproveSalienceSchema = z
      */
     replayBudget: z.number().int().min(0).optional(),
 })
-    .strict();
+    .passthrough();
 export const ImproveConfigSchema = z
     .object({
     utilityDecay: ImproveUtilityDecaySchema.optional(),
@@ -633,7 +619,7 @@ export const ImproveConfigSchema = z
     exploration: ImproveExplorationSchema.optional(),
     salience: ImproveSalienceSchema.optional(),
 })
-    .strict();
+    .passthrough();
 // ── Index / per-pass ────────────────────────────────────────────────────────
 const GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED = [
     "memory",
@@ -712,13 +698,13 @@ export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
     lazyGraphExtraction: z.boolean().optional(),
 })
     .passthrough());
-const MetadataEnhanceSchema = z.object({ enabled: z.boolean().optional() }).strict();
+const MetadataEnhanceSchema = z.object({ enabled: z.boolean().optional() }).passthrough();
 const StalenessDetectionSchema = z
     .object({
     enabled: z.boolean().optional(),
     thresholdDays: positiveInt.optional(),
 })
-    .strict();
+    .passthrough();
 /**
  * Index config is a union of reserved feature sections and per-pass entries.
  * Passthrough so per-pass entries (keyed by arbitrary pass names like `graph`,
@@ -791,12 +777,12 @@ export const SetupTaskSchedulesSchema = z
     improve: z.string().min(1).optional(),
     index: z.string().min(1).optional(),
 })
-    .strict();
+    .passthrough();
 export const SetupConfigSchema = z
     .object({
     taskSchedules: SetupTaskSchedulesSchema.optional(),
 })
-    .strict();
+    .passthrough();
 // ── Top-level AkmConfig ────────────────────────────────────────────────────
 /**
  * Base object schema used both as the top-level shape and as the source of
@@ -828,7 +814,7 @@ export const AkmConfigShape = {
     improve: ImproveConfigSchema.optional(),
     setup: SetupConfigSchema.optional(),
 };
-export const AkmConfigBaseSchema = z.object(AkmConfigShape).strict();
+export const AkmConfigBaseSchema = z.object(AkmConfigShape).passthrough();
 export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
     // #464.a: defaultWriteTarget must name a configured source when sources
     // are present. With no sources configured, error out instead of silently

package/dist/indexer/search/semantic-status.js

@@ -4,8 +4,12 @@
 import fs from "node:fs";
 import { writeFileAtomic } from "../../core/common.js";
 import { getCacheDir, getSemanticStatusPath } from "../../core/paths.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../../llm/embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL } from "../../llm/embedders/local.js";
 export function deriveSemanticProviderFingerprint(embedding) {
+    if (isDeterministicEmbedEnabled()) {
+        return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
+    }
     if (embedding?.endpoint) {
         return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;
     }

package/dist/llm/embedder.js

@@ -2,6 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, deterministicEmbed, isDeterministicEmbedEnabled, } from "./embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
@@ -39,6 +40,10 @@ export function resetLocalEmbedder() {
  * and embedding config. Repeated identical queries return the cached vector.
  */
 export async function embed(text, embeddingConfig, signal) {
+    // Deterministic mode (env-gated, test/bench only): model-free, stable.
+    if (isDeterministicEmbedEnabled()) {
+        return deterministicEmbed(text);
+    }
     const key = embedCacheKey(text, embeddingConfig);
     const cached = getCachedEmbedding(key);
     if (cached)
@@ -58,6 +63,10 @@ export async function embed(text, embeddingConfig, signal) {
 export async function embedBatch(texts, embeddingConfig, signal) {
     if (texts.length === 0)
         return [];
+    // Deterministic mode (env-gated, test/bench only): model-free, stable.
+    if (isDeterministicEmbedEnabled()) {
+        return texts.map((t) => deterministicEmbed(t));
+    }
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal);
     }
@@ -95,6 +104,8 @@ export { cosineSimilarity } from "./embedders/types.js";
  *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
  */
 export function resolveEmbeddingModelId(embeddingConfig) {
+    if (isDeterministicEmbedEnabled())
+        return DETERMINISTIC_EMBED_MODEL_ID;
     if (!embeddingConfig)
         return DEFAULT_LOCAL_MODEL;
     if (hasRemoteEndpoint(embeddingConfig))
@@ -106,6 +117,10 @@ export function resolveEmbeddingModelId(embeddingConfig) {
  * Check whether embedding is available with a detailed reason on failure.
  */
 export async function checkEmbeddingAvailability(embeddingConfig) {
+    // Deterministic mode (env-gated): always available — no model, no network.
+    if (isDeterministicEmbedEnabled()) {
+        return { available: true };
+    }
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         try {
             await new RemoteEmbedder(embeddingConfig).embed("test");

package/dist/llm/embedders/deterministic.js

@@ -0,0 +1,66 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/** Env var that switches the whole embedding facade into deterministic mode. */
+export const DETERMINISTIC_EMBED_ENV = "AKM_EMBED_DETERMINISTIC";
+/**
+ * Vector width. Matches the default local model (`bge-small`, 384 dims) so the
+ * index DB's embedding column and sqlite-vec table dimensions line up without
+ * any extra config.
+ */
+export const DETERMINISTIC_EMBED_DIM = 384;
+/**
+ * Stable model id reported for deterministic mode. Used as the embedding
+ * `model_id` and folded into the provider fingerprint so a deterministic index
+ * is never confused with a real-model index (and vice versa).
+ */
+export const DETERMINISTIC_EMBED_MODEL_ID = "akm-deterministic-hash-v1";
+/** True when deterministic embedding is enabled via env. */
+export function isDeterministicEmbedEnabled() {
+    return process.env[DETERMINISTIC_EMBED_ENV] === "1";
+}
+/** FNV-1a 32-bit hash. Platform- and version-stable. */
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        // 32-bit FNV prime multiply via shifts to stay in uint32.
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h >>> 0;
+}
+/** Lowercase, split on non-alphanumeric, drop empties. */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Deterministically embed `text` into a unit-length vector of width `dim`
+ * using feature hashing. Empty / token-less input returns a fixed unit
+ * vector so cosine similarity never sees a zero vector (NaN guard).
+ */
+export function deterministicEmbed(text, dim = DETERMINISTIC_EMBED_DIM) {
+    const vec = new Array(dim).fill(0);
+    const tokens = tokenize(text);
+    for (const tok of tokens) {
+        const h = fnv1a(tok);
+        const idx = h % dim;
+        // Use a higher bit for the sign so it is independent of the bucket index.
+        const sign = (h >>> 16) & 1 ? 1 : -1;
+        vec[idx] += sign;
+    }
+    let norm = 0;
+    for (const v of vec)
+        norm += v * v;
+    norm = Math.sqrt(norm);
+    if (norm === 0) {
+        // No usable tokens — return a fixed, stable unit vector.
+        vec[0] = 1;
+        return vec;
+    }
+    for (let i = 0; i < dim; i++)
+        vec[i] /= norm;
+    return vec;
+}

package/dist/scripts/migrate-storage.js

@@ -15785,7 +15785,7 @@ var init_config_schema = __esm(() => {
   });
   LlmCapabilitiesSchema = exports_external.object({
     structuredOutput: exports_external.boolean().optional()
-  }).strict();
+  }).passthrough();
   LlmConnectionConfigSchema = exports_external.object({
     provider: exports_external.string().optional(),
     endpoint: exports_external.string(),
@@ -15800,13 +15800,13 @@ var init_config_schema = __esm(() => {
     contextLength: positiveInt.optional(),
     judgeModel: exports_external.string().min(1).optional(),
     enableThinking: exports_external.boolean().optional()
-  }).strict();
+  }).passthrough();
   LlmProfileConfigSchema = LlmConnectionConfigSchema.extend({
     supportsJsonSchema: exports_external.boolean().optional()
-  }).strict();
+  }).passthrough();
   EmbeddingOllamaOptionsSchema = exports_external.object({
     num_ctx: positiveInt.optional()
-  }).strict();
+  }).passthrough();
   EmbeddingConnectionConfigSchema = exports_external.object({
     provider: exports_external.string().optional(),
     endpoint: exports_external.string().optional(),
@@ -15819,7 +15819,7 @@ var init_config_schema = __esm(() => {
     chunkSize: positiveInt.optional(),
     contextLength: positiveInt.optional(),
     ollamaOptions: EmbeddingOllamaOptionsSchema.optional()
-  }).strict();
+  }).passthrough();
   AgentPlatformSchema = exports_external.enum(VALID_HARNESS_IDS);
   AgentProfileConfigSchema = exports_external.object({
     platform: AgentPlatformSchema,
@@ -15827,7 +15827,7 @@ var init_config_schema = __esm(() => {
     args: exports_external.array(exports_external.string()).optional(),
     workspace: exports_external.string().min(1).optional(),
     model: exports_external.string().min(1).optional()
-  }).strict();
+  }).passthrough();
   ImproveProcessConfigSchema = exports_external.object({
     enabled: exports_external.boolean().optional(),
     mode: exports_external.enum(["llm", "agent", "sdk"]).optional(),
@@ -15839,10 +15839,10 @@ var init_config_schema = __esm(() => {
       enabled: exports_external.boolean().optional(),
       cosineThreshold: exports_external.number().min(0).max(1).optional(),
       cosineCandidateLimit: exports_external.number().int().positive().optional()
-    }).strict().optional(),
-    judgedCache: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
-    qualityGate: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
-    contradictionDetection: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
+    }).passthrough().optional(),
+    judgedCache: exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional(),
+    qualityGate: exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional(),
+    contradictionDetection: exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional(),
     defaultSince: exports_external.string().min(1).optional(),
     maxTotalChars: positiveInt.optional(),
     minContentChars: exports_external.number().int().min(0).optional(),
@@ -15864,28 +15864,28 @@ var init_config_schema = __esm(() => {
       enabled: exports_external.boolean().optional(),
       staleDays: exports_external.number().int().min(0).optional(),
       demotionFactor: exports_external.number().min(0).max(1).optional()
-    }).strict().optional(),
+    }).passthrough().optional(),
     schemaSimilarity: exports_external.object({
       enabled: exports_external.boolean().optional(),
       epsilon: exports_external.number().min(0).max(1).optional(),
       confidencePenalty: exports_external.number().min(0).max(1).optional()
-    }).strict().optional(),
+    }).passthrough().optional(),
     hotProbation: exports_external.object({
       enabled: exports_external.boolean().optional()
-    }).strict().optional(),
+    }).passthrough().optional(),
     antiCollapse: exports_external.object({
       enabled: exports_external.boolean().optional(),
       maxGeneration: exports_external.number().int().min(1).optional(),
       lexicalDiversityCheck: exports_external.boolean().optional(),
       randomClusterFraction: exports_external.number().min(0).max(1).optional()
-    }).strict().optional(),
+    }).passthrough().optional(),
     cls: exports_external.object({
       enabled: exports_external.boolean().optional(),
       adjacentCount: exports_external.number().int().min(1).optional()
-    }).strict().optional(),
+    }).passthrough().optional(),
     fidelityCheck: exports_external.object({
       enabled: exports_external.boolean().optional()
-    }).strict().optional(),
+    }).passthrough().optional(),
     minClusterSize: exports_external.number().int().min(2).optional(),
     maxClustersPerRun: positiveInt.optional(),
     maxClusterSize: positiveInt.optional(),
@@ -15896,7 +15896,7 @@ var init_config_schema = __esm(() => {
     minRecurrence: exports_external.number().int().min(2).optional(),
     maxProposalsPerRun: positiveInt.optional(),
     emitAs: exports_external.enum(["workflow", "skill"]).optional(),
-    lowValueFilter: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
+    lowValueFilter: exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional(),
     proceduralAwareFloor: exports_external.boolean().optional(),
     applyMode: exports_external.enum(["queue", "promote"]).optional(),
     policy: exports_external.string().min(1).optional(),
@@ -15907,8 +15907,8 @@ var init_config_schema = __esm(() => {
       mode: exports_external.enum(["llm", "agent", "sdk"]).optional(),
       profile: exports_external.string().min(1).optional(),
       timeoutMs: exports_external.union([positiveInt, exports_external.null()]).optional()
-    }).strict().optional()
-  }).strict();
+    }).passthrough().optional()
+  }).passthrough();
   ImproveProfileProcessesSchema = exports_external.object({
     reflect: ImproveProcessConfigSchema.optional(),
     distill: ImproveProcessConfigSchema.optional(),
@@ -15921,35 +15921,11 @@ var init_config_schema = __esm(() => {
     recombine: ImproveProcessConfigSchema.optional(),
     procedural: ImproveProcessConfigSchema.optional()
   }).passthrough().superRefine((val, ctx) => {
-    const raw = val;
-    if ("feedbackDistillation" in raw) {
+    if ("feedbackDistillation" in val) {
       ctx.addIssue({
         code: exports_external.ZodIssueCode.custom,
         message: "feedbackDistillation was removed in 0.8.0 \u2014 use processes.distill.enabled instead. " + "It now controls both the orchestration gate and the LLM-call gate."
       });
-      return;
-    }
-    const allowed = new Set([
-      "reflect",
-      "distill",
-      "consolidate",
-      "memoryInference",
-      "graphExtraction",
-      "validation",
-      "extract",
-      "triage",
-      "proactiveMaintenance",
-      "recombine",
-      "procedural"
-    ]);
-    for (const k of Object.keys(raw)) {
-      if (!allowed.has(k)) {
-        ctx.addIssue({
-          code: exports_external.ZodIssueCode.unrecognized_keys,
-          keys: [k],
-          message: `Unrecognized improve process key: "${k}".`
-        });
-      }
     }
   });
   ImproveProfileConfigSchema = exports_external.object({
@@ -15963,18 +15939,18 @@ var init_config_schema = __esm(() => {
       enabled: exports_external.boolean().optional(),
       push: exports_external.boolean().optional(),
       message: exports_external.string().min(1).optional()
-    }).strict().optional()
-  }).strict();
+    }).passthrough().optional()
+  }).passthrough();
   ProfilesSchema = exports_external.object({
     llm: exports_external.record(exports_external.string(), LlmProfileConfigSchema).optional(),
     agent: exports_external.record(exports_external.string(), AgentProfileConfigSchema).optional(),
     improve: exports_external.record(exports_external.string(), ImproveProfileConfigSchema).optional()
-  }).strict();
+  }).passthrough();
   DefaultsSchema = exports_external.object({
     llm: exports_external.string().min(1).optional(),
     agent: exports_external.string().min(1).optional(),
     improve: exports_external.string().min(1).optional()
-  }).strict();
+  }).passthrough();
   SourceConfigEntryOptionsSchema = exports_external.object({
     pushOnCommit: exports_external.boolean().optional()
   }).passthrough();
@@ -15988,7 +15964,7 @@ var init_config_schema = __esm(() => {
     primary: exports_external.boolean().optional(),
     options: SourceConfigEntryOptionsSchema.optional(),
     wikiName: exports_external.string().min(1).optional()
-  }).strict().superRefine((entry, ctx) => {
+  }).passthrough().superRefine((entry, ctx) => {
     if (entry.writable === true && (entry.type === "website" || entry.type === "npm")) {
       ctx.addIssue({
         code: exports_external.ZodIssueCode.custom,
@@ -16002,7 +15978,7 @@ var init_config_schema = __esm(() => {
     enabled: exports_external.boolean().optional(),
     provider: exports_external.string().min(1).optional(),
     options: exports_external.record(exports_external.unknown()).optional()
-  }).strict();
+  }).passthrough();
   KitSourceSchema = exports_external.enum(["filesystem", "git", "npm", "github", "website", "local"]);
   InstalledStashEntrySchema = exports_external.object({
     id: nonEmptyString,
@@ -16016,7 +15992,7 @@ var init_config_schema = __esm(() => {
     resolvedVersion: exports_external.string().min(1).optional(),
     resolvedRevision: exports_external.string().min(1).optional(),
     wikiName: exports_external.string().min(1).optional()
-  }).strict().superRefine((entry, ctx) => {
+  }).passthrough().superRefine((entry, ctx) => {
     if (entry.writable === true && entry.source !== "git" && entry.source !== "filesystem") {
       ctx.addIssue({
         code: exports_external.ZodIssueCode.custom,
@@ -16027,7 +16003,7 @@ var init_config_schema = __esm(() => {
   OutputConfigSchema = exports_external.object({
     format: exports_external.enum(["json", "yaml", "text"]).optional(),
     detail: exports_external.enum(["brief", "normal", "full"]).optional()
-  }).strict();
+  }).passthrough();
   SearchGraphBoostSchema = exports_external.object({
     directBoostPerEntity: nonNegativeNumber.optional(),
     directBoostCap: nonNegativeNumber.optional(),
@@ -16036,21 +16012,21 @@ var init_config_schema = __esm(() => {
     maxHops: positiveInt.max(3).optional(),
     confidenceMode: exports_external.enum(["off", "blend", "multiply"]).default("blend").optional(),
     confidenceWeight: exports_external.number().finite().min(0).max(1).default(0.2).optional()
-  }).strict();
+  }).passthrough();
   SearchConfigSchema = exports_external.object({
     minScore: nonNegativeNumber.optional(),
     defaultExcludeTypes: exports_external.array(nonEmptyString).optional(),
-    curateRerank: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
+    curateRerank: exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional(),
     graphBoost: SearchGraphBoostSchema.optional()
-  }).strict();
+  }).passthrough();
   FeedbackConfigSchema = exports_external.object({
     requireReason: exports_external.boolean().optional(),
     allowedFailureModes: exports_external.array(nonEmptyString).optional()
-  }).strict();
+  }).passthrough();
   ImproveUtilityDecaySchema = exports_external.object({
     halfLifeDays: exports_external.number().finite().min(0.1).optional(),
     feedbackStabilityBoost: exports_external.number().finite().min(1).optional()
-  }).strict();
+  }).passthrough();
   ImproveCalibrationSchema = exports_external.object({
     autoTune: exports_external.boolean().optional(),
     minThreshold: exports_external.number().int().min(0).max(100).optional(),
@@ -16058,23 +16034,23 @@ var init_config_schema = __esm(() => {
     maxStep: positiveInt.optional(),
     minSamples: nonNegativeNumber.optional(),
     targetAcceptRate: exports_external.number().finite().min(0).max(1).optional()
-  }).strict();
+  }).passthrough();
   ImproveExplorationSchema = exports_external.object({
     enabled: exports_external.boolean().optional(),
     budgetFraction: exports_external.number().finite().min(0).max(1).optional()
-  }).strict();
+  }).passthrough();
   ImproveSalienceSchema = exports_external.object({
     outcomeWeightEnabled: exports_external.boolean().optional(),
     salienceThreshold: exports_external.number().min(0).max(1).optional(),
     replayBudget: exports_external.number().int().min(0).optional()
-  }).strict();
+  }).passthrough();
   ImproveConfigSchema = exports_external.object({
     utilityDecay: ImproveUtilityDecaySchema.optional(),
     eventRetentionDays: nonNegativeNumber.optional(),
     calibration: ImproveCalibrationSchema.optional(),
     exploration: ImproveExplorationSchema.optional(),
     salience: ImproveSalienceSchema.optional()
-  }).strict();
+  }).passthrough();
   GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED = [
     "memory",
     "knowledge",
@@ -16140,11 +16116,11 @@ var init_config_schema = __esm(() => {
     memoryInferenceBatchSize: positiveInt.optional(),
     lazyGraphExtraction: exports_external.boolean().optional()
   }).passthrough());
-  MetadataEnhanceSchema = exports_external.object({ enabled: exports_external.boolean().optional() }).strict();
+  MetadataEnhanceSchema = exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough();
   StalenessDetectionSchema = exports_external.object({
     enabled: exports_external.boolean().optional(),
     thresholdDays: positiveInt.optional()
-  }).strict();
+  }).passthrough();
   IndexConfigSchema = exports_external.preprocess((raw, ctx) => {
     if (raw === undefined || raw === null)
       return raw;
@@ -16190,10 +16166,10 @@ var init_config_schema = __esm(() => {
   SetupTaskSchedulesSchema = exports_external.object({
     improve: exports_external.string().min(1).optional(),
     index: exports_external.string().min(1).optional()
-  }).strict();
+  }).passthrough();
   SetupConfigSchema = exports_external.object({
     taskSchedules: SetupTaskSchedulesSchema.optional()
-  }).strict();
+  }).passthrough();
   AkmConfigShape = {
     configVersion: exports_external.union([exports_external.string().min(1), exports_external.number()]).optional(),
     profiles: ProfilesSchema.optional(),
@@ -16214,7 +16190,7 @@ var init_config_schema = __esm(() => {
     improve: ImproveConfigSchema.optional(),
     setup: SetupConfigSchema.optional()
   };
-  AkmConfigBaseSchema = exports_external.object(AkmConfigShape).strict();
+  AkmConfigBaseSchema = exports_external.object(AkmConfigShape).passthrough();
   AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
     if (config.defaultWriteTarget !== undefined) {
       const knownNames = (config.sources ?? []).map((s) => s.name).filter((n) => typeof n === "string" && n.length > 0);

package/dist/sources/wiki-fetchers/youtube.js

@@ -4,6 +4,21 @@
 import { fetchWithRetry } from "../../core/common.js";
 const YOUTUBE_HOSTS = new Set(["www.youtube.com", "youtube.com", "m.youtube.com", "youtu.be"]);
 const WATCH_HOST = "https://www.youtube.com/watch?v=";
+// Captions: the WEB watch-page caption baseUrls are now Proof-of-Origin-Token
+// gated (they carry `exp=xpe` and return an empty body without a `pot` token).
+// The ANDROID InnerTube `player` client still returns UNGATED caption baseUrls
+// that serve the transcript, so captions are sourced from there. See
+// https://github.com/yt-dlp/yt-dlp/issues/13075.
+const INNERTUBE_PLAYER_URL = "https://www.youtube.com/youtubei/v1/player";
+// Long-stable public InnerTube key; only authorizes the player call (not auth).
+const DEFAULT_INNERTUBE_KEY = "AIzaSyAO_FJ2SlqU8Q4STEHLGCilw_Y9_11qcW8";
+const ANDROID_INNERTUBE_CLIENT = {
+    clientName: "ANDROID",
+    clientVersion: "20.10.38",
+    androidSdkVersion: 34,
+    hl: "en",
+    gl: "US",
+};
 function extractVideoId(url) {
     if (!YOUTUBE_HOSTS.has(url.hostname))
         return null;
@@ -19,6 +34,10 @@ function extractVideoId(url) {
         const id = url.pathname.slice("/shorts/".length).split("/")[0]?.trim();
         return id || null;
     }
+    if (url.pathname.startsWith("/embed/")) {
+        const id = url.pathname.slice("/embed/".length).split("/")[0]?.trim();
+        return id || null;
+    }
     return null;
 }
 function canonicalWatchUrl(videoId) {
@@ -125,13 +144,45 @@ async function fetchText(url, timeoutMs, signal) {
     return response.text();
 }
 function parseTranscript(xml) {
-    const texts = [...xml.matchAll(/<text\b[^>]*>([\s\S]*?)<\/text>/g)]
-        .map((match) => decodeEntities(stripTags(match[1] ?? "")).trim())
-        .filter(Boolean);
+    // Two timedtext shapes: legacy srv1 `<text>` cues, and the format-3
+    // `<timedtext format="3">` `<p>` cues that the ANDROID InnerTube caption
+    // URLs return. Strip any nested `<s>` word tags via stripTags.
+    const matches = [...xml.matchAll(/<text\b[^>]*>([\s\S]*?)<\/text>/g), ...xml.matchAll(/<p\b[^>]*>([\s\S]*?)<\/p>/g)];
+    const texts = matches.map((match) => decodeEntities(stripTags(match[1] ?? "")).trim()).filter(Boolean);
     if (texts.length === 0)
         return null;
     return texts.join("\n");
 }
+/**
+ * Fetch caption tracks via the ANDROID InnerTube `player` endpoint, whose
+ * caption baseUrls are not POT-gated. Returns [] on any failure so the caller
+ * can fall back to the (usually empty) watch-page tracks and degrade to a
+ * description-only snapshot.
+ */
+async function fetchInnertubeCaptionTracks(videoId, apiKey, timeoutMs, signal) {
+    try {
+        const response = await fetchWithRetry(`${INNERTUBE_PLAYER_URL}?key=${encodeURIComponent(apiKey)}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": "com.google.android.youtube/20.10.38 (Linux; U; Android 14) gzip",
+            },
+            body: JSON.stringify({ context: { client: ANDROID_INNERTUBE_CLIENT }, videoId }),
+            signal,
+        }, { timeout: timeoutMs, retries: 1 });
+        if (!response.ok)
+            return [];
+        const json = (await response.json());
+        return json.captions?.playerCaptionsTracklistRenderer?.captionTracks ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Extract the page's InnerTube API key, falling back to the stable default. */
+function extractInnertubeKey(html) {
+    return html.match(/"INNERTUBE_API_KEY":"([^"]+)"/)?.[1] ?? DEFAULT_INNERTUBE_KEY;
+}
 const youtubeFetcher = {
     name: "youtube-transcript",
     matches(url) {
@@ -157,7 +208,14 @@ const youtubeFetcher = {
         if (description) {
             sections.push("## Description", "", description);
         }
-        const tracks = playerResponse.captions?.playerCaptionsTracklistRenderer?.captionTracks ?? [];
+        // Prefer ungated ANDROID InnerTube caption tracks; fall back to the
+        // (now usually empty) watch-page tracks so a description-only snapshot
+        // still works when InnerTube is unavailable.
+        const apiKey = extractInnertubeKey(watchHtml);
+        let tracks = await fetchInnertubeCaptionTracks(videoId, apiKey, context.timeoutMs, context.signal);
+        if (tracks.length === 0) {
+            tracks = playerResponse.captions?.playerCaptionsTracklistRenderer?.captionTracks ?? [];
+        }
         const captionUrl = chooseCaptionTrack(tracks);
         if (captionUrl) {
             const transcriptXml = await fetchText(captionUrl, context.timeoutMs, context.signal);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.46",
+  "version": "0.9.0-beta.48",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [