@tenphi/akno-core 0.1.0

package/LICENSE

@@ -0,0 +1,83 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright 2026 Andrey Yamanov (https://github.com/tenphi/akno)
+
+Akno is source-available, not open source. Personal and other noncommercial
+use is free. Using it commercially — including as part of, or to operate, a
+paid product or service — is not permitted under these terms. For a commercial
+licence, ask.
+
+Third-party dependencies are not covered by these terms. Each remains under
+its own licence and the copyright of its own authors.
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,26 @@
+# @tenphi/akno-core
+
+The memory layer itself: config, store, indexer, models, recall, the write path, the watcher and the
+maintenance cycle. This is the engine behind the [`@tenphi/akno`](https://www.npmjs.com/package/@tenphi/akno)
+CLI, published separately so a host can embed it in-process.
+
+macOS only (`"os": ["darwin"]`), and it carries native dependencies — `better-sqlite3` and `sqlite-vec`. A
+host that only needs to _talk_ to a running Akno should depend on
+[`@tenphi/akno-client`](https://www.npmjs.com/package/@tenphi/akno-client) instead, which is portable and
+has no native code.
+
+```ts
+import { open } from '@tenphi/akno-core';
+
+const akno = await open({ aknoPath: '~/Notes' });
+const result = await akno.call('recall', { query: 'car insurance renewal' });
+```
+
+Exactly one process may hold the write handle. A second `open` on the same state directory returns a
+read-only handle and says so, rather than racing a live watcher.
+
+Full documentation: [github.com/tenphi/akno](https://github.com/tenphi/akno#readme)
+
+## License
+
+PolyForm Noncommercial License 1.0.0 © Andrey Yamanov — noncommercial use only.

package/config/default.jsonc

@@ -0,0 +1,548 @@
+{
+  // ───────────────────────────────────────────────────────────────────────────
+  // Akno — committed defaults.
+  //
+  // This file is version-controlled and must stay machine-independent: no home
+  // paths, no endpoints, no credentials, no model ids that assume a particular
+  // server. Override anything here in `config/local.jsonc` (gitignored) or in
+  // `~/.akno/config.json`.
+  //
+  // Precedence, lowest to highest:
+  //   config/default.jsonc → ~/.akno/config.json → config/local.jsonc → AKNO_* env
+  // ───────────────────────────────────────────────────────────────────────────
+
+  // The Markdown knowledge base. Null on purpose: Akno refuses to start
+  // rather than guessing which folder holds your notes.
+  "akno_path": null,
+
+  // Everything Akno derives — the index, the trash, the journal, logs, the
+  // socket. Deleting it costs one re-index and no data.
+  "state_dir": "~/.akno",
+
+  // ─── Reserved paths ───────────────────────────────────────────────────────
+  // Remappable so a collision with something you already have is resolvable.
+  // Relative to akno_path.
+  "paths": {
+    "timeline": "timeline.md",
+    "inbox": "inbox",
+    "observations": "observations",
+    "journal": "journal"
+  },
+
+  // Create `timeline.md` and `inbox/` on startup if missing. Off by default so
+  // a first run against an existing knowledge base changes nothing at all.
+  "create_reserved_paths": false,
+
+  // ─── Identity ─────────────────────────────────────────────────────────────
+  // Akno's only write into a page is a frontmatter `id:`. Off by default: the
+  // sidecar map in akno.db carries identity, and renames are followed by body
+  // hash. Turn this on for identity that survives `rm akno.db` and a move to
+  // another machine.
+  "write_ids": false,
+
+  // ─── Ingestion & structure ────────────────────────────────────────────────
+  // Directories never walked, at any depth.
+  "ignore": [".git", ".obsidian", ".trash", ".akno", "node_modules", ".DS_Store", ".stfolder", ".stversions"],
+  // Extensions indexed as pages. Everything else is an attachment candidate.
+  "page_extensions": [".md", ".markdown"],
+  // Bytes above which a page is chunked but not summarized or fact-mined.
+  "max_page_bytes": 1048576,
+
+  // ─── Declaring folders ────────────────────────────────────────────────────
+  // How deep a folder must be *described* before a page can appear in it. Not an approval:
+  // nothing here reaches the user. A write into an undeclared folder comes back
+  // `requires_folder`, the caller says what belongs there with the `folder` op — ungated —
+  // and repeats the write.
+  //
+  // "top-level" | "all" | "none". A folder the user makes by hand is theirs and is never
+  // questioned; this only sees what an agent creates.
+  "gate": "top-level",
+  // Below this score `remember` and inbox routing propose instead of writing.
+  // 0.5 is a starting default, not a measured one.
+  "route_threshold": 0.5,
+  // "ledger" | "daily" — where an event with no page behind it lands.
+  "loose_events": "ledger",
+  // "none" | "summary" | "all" — write derived data back into frontmatter as a
+  // body-hash-keyed cache. Visible in Obsidian; a stale entry is never trusted.
+  "derived_in_frontmatter": "none",
+
+  // ─── Providers ────────────────────────────────────────────────────────────
+  // Any OpenAI-compatible endpoint. `api_key` names an env var; it never holds
+  // a key. One local server can host every role.
+  // Null endpoint on purpose: committed defaults assume nothing about this
+  // machine, not even that something is listening on a well-known port. Set this
+  // in config/local.jsonc — `akno doctor` reports every role that has no
+  // endpoint and what its absence costs.
+  "providers": {
+    "local": {
+      "base_url": null,
+      "api_key": null,
+      // Generative transport only; embeddings and native reranking keep their
+      // dedicated endpoints. Third-party OpenAI-compatible servers default to
+      // Chat Completions. Use "auto" to run one invented capability probe and
+      // cache the result; the guided OpenAI preset explicitly uses Responses.
+      "api": "chat_completions",
+      // Retries after a rate limit (429) or a transient server error (500, 502,
+      // 503, 504), with exponential backoff and full jitter. A `Retry-After`
+      // header is obeyed when one is sent.
+      //
+      // What it costs to change: on the recall path, nothing — `recall.expansion_
+      // timeout_ms` is the budget for the whole sequence, so a retry happens only
+      // if there is time left inside it and a retrying recall can never be slower
+      // than one with retries off.
+      //
+      // Everywhere else a role's `timeout_ms` is per *attempt*, because it is a
+      // backstop against an endpoint that has gone quiet and nothing waits on a
+      // background derivation. So this multiplies the worst case: 2 against
+      // derive's 300s is 900s plus backoff for one page, in the case where an
+      // endpoint returns a slow 5xx three times running. Lower it if that matters
+      // more than the page; 0 turns retrying off entirely.
+      //
+      // A timeout is never retried: the attempt has already spent its deadline,
+      // and the callers that care have a better answer than repetition (a
+      // derivation that times out asks for the summary alone, which is cheaper
+      // *and* likelier to land than the identical request a second time).
+      "max_retries": 2
+    }
+  },
+
+  // ─── Models ───────────────────────────────────────────────────────────────
+  // Six roles, all optional, each degrading rather than failing. `id: null`
+  // means the role is unconfigured — Akno reports it in `doctor` and takes
+  // the documented degraded path.
+  "models": {
+    // Without it: lexical search only.
+    "embedding": {
+      "provider": "local",
+      "id": null,
+      "dimensions": 1024,
+      "batch": 32,
+      "timeout_ms": 60000
+    },
+    // Without it: hybrid score ordering.
+    "reranker": {
+      "provider": "local",
+      "id": null,
+      "enabled": false,
+      // "endpoint" calls a native cross-encoder at /rerank. "llm" uses the
+      // versioned Akno listwise prompt over the provider's generative transport.
+      "mode": "endpoint",
+      // A successful reranker may remove confidently irrelevant candidates.
+      // Unjudged candidates outside top_k are omitted rather than used to fill
+      // the holes, because the model made no qualification claim about them.
+      "exclude_irrelevant": true,
+      // Candidates re-scored. This is the reranker's whole latency dial: cost is
+      // per candidate, not per character. Measured on 223 pages against a local
+      // bge-reranker-v2-m3, over 8 queries, compared to top_k 40:
+      //
+      //   top_k 40   1036 ms   (reference)
+      //   top_k 30    886 ms   same top hit every time, 36/40 results unchanged
+      //   top_k 20    646 ms   one different top hit, 30/40 results unchanged
+      //
+      // 40 is the default because the cheaper settings change *which pages come
+      // back*, and 400 ms is not worth a different answer. Lower it if you would
+      // rather have the latency, now that you know what it costs.
+      //
+      // LLM mode still sends exactly top_k candidates. It preserves the first
+      // top_k - 1 fused hits and uses the final slot for the strongest vector-ranked
+      // candidate from a bounded 2 × top_k pool. This recovers a strong paraphrase
+      // just beyond the fusion boundary without increasing model tokens.
+      "top_k": 40,
+      // Characters of each candidate sent. Measured free — truncating from 4,000 to
+      // 800 changed neither latency (1036 → 1028 ms) nor a single result. Kept
+      // because it bounds the request payload and costs nothing: a cross-encoder's
+      // relevance signal is front-loaded.
+      "max_chars": 800,
+      // Native endpoints do not share a score scale. "auto" learns a conservative
+      // boundary from invented anchors, caches it for seven days, and refuses to
+      // filter if those anchors do not separate. A measured number overrides it.
+      "score_offset": "auto",
+      // Used only by mode "llm". Set reasoning explicitly for hosted reasoning
+      // models so ranking latency and cost do not inherit a provider default.
+      "max_output_tokens": 1600,
+      "reasoning_effort": null,
+      "timeout_ms": 30000
+    },
+    // The quality role: page summaries, keywords, fact derivation, `remember`,
+    // naming an arrival, and every maintenance tier. None of it is on the recall
+    // path, so this one is allowed to be slow and good.
+    //
+    // Without it: no summaries, no keywords, no fact derivation, no `remember`,
+    // no naming, no observations. Recall still works.
+    "derive": {
+      "provider": "local",
+      "id": null,
+      // A ceiling on this role, and the *lower* of it and what a task asks for is what gets sent.
+      // 2400 because that is what a full page derivation needs to answer in JSON — a summary,
+      // keywords, and every durable claim on the page. Lower it and long pages start returning
+      // truncated JSON, which costs their facts (the summary is recovered on its own). Every
+      // cheaper caller already asks for less and is unaffected: 700 for an observation, 500 to name
+      // an arrival, 200 for a conflict verdict.
+      "max_output_tokens": 2400,
+      // null uses the provider default. Hosted reasoning models can set one of
+      // "none", "low", "medium", "high", "xhigh", or "max" per role.
+      "reasoning_effort": null,
+      // Pages derived at once during a sweep. Raise it for a bigger endpoint;
+      // a single local server usually does no better than 2.
+      "concurrency": 2,
+      "timeout_ms": 120000
+    },
+    // The latency role: query expansion, and nothing else. It runs on every
+    // recall that asks for it, so a small fast model is the right answer here
+    // even when `derive` points at something much stronger. Pointing both at one
+    // model is fine too.
+    //
+    // Without it: recall searches the words you typed and nothing more.
+    "expansion": {
+      "provider": "local",
+      "id": null,
+      // Expansion asks for 400; this only has to be above it.
+      "max_output_tokens": 1024,
+      "reasoning_effort": null,
+      "concurrency": 2,
+      // A backstop, not the deadline — `recall.expansion_timeout_ms` governs a
+      // call. This one only catches an endpoint that accepts and goes quiet.
+      "timeout_ms": 30000
+    },
+    // Direct grounded synthesis. If this block is omitted from an overlay,
+    // Akno inherits the derive model so an existing single-endpoint setup
+    // does not need another model declaration. A separate role lets interactive
+    // answering keep a smaller output ceiling and timeout.
+    "answer": {
+      "provider": "local",
+      "id": null,
+      "max_output_tokens": 1024,
+      "reasoning_effort": null,
+      "concurrency": 2,
+      "timeout_ms": 60000
+    },
+    // Off by default. OCR covers scans and screenshots, which is most arrivals.
+    "vision": {
+      "provider": "local",
+      "id": null,
+      "enabled": false,
+      "reasoning_effort": null,
+      "timeout_ms": 120000
+    }
+  },
+
+  // ─── Indexing ─────────────────────────────────────────────────────────────
+  "index": {
+    // Chunks follow the document's own headings; these are the size gates.
+    "chunk_target_chars": 1200,
+    "chunk_max_chars": 4000,
+    "chunk_overlap_chars": 120,
+    // Model-backed derivation. Each is independently skippable, and skipping
+    // one degrades a feature rather than failing the index.
+    "summaries": true,
+    "facts": true,
+    // Files hashed concurrently during a sweep.
+    "hash_concurrency": 8,
+    // Switch on sqlite-vec's ANN index above this many chunks. Brute force is
+    // strictly better below it.
+    "ann_threshold_chunks": 20000
+  },
+
+  // ─── Evidence graph ─────────────────────────────────────────────────────
+  "graph": {
+    "contextual_resolution": {
+      // Exact aliases remain the default. Turn this on only after
+      // `akno bench entities` passes against the configured derive model.
+      // The model may choose among existing exact-name candidates or abstain;
+      // it cannot create, merge, or rename entities.
+      "enabled": false,
+      "max_candidates": 8,
+      "max_mentions_per_index": 20,
+      "reasoning_effort": "none"
+    }
+  },
+
+  // ─── Recall ───────────────────────────────────────────────────────────────
+  "recall": {
+    "default_budget": 8000,
+    "default_limit": 8,
+    // Candidates pulled from each arm of the hybrid search before fusion.
+    "candidates_per_arm": 60,
+    // Lines of body returned per card in lookup mode.
+    "line_window": 6,
+    // Hard cap on what a `source` page contributes unprompted. A guess, not a
+    // measurement.
+    "source_quote_lines": 6,
+    // Query expansion — off means the query is searched verbatim.
+    "expansion": true,
+    // Expansion is optional, so it gets its own short deadline rather than the
+    // role's ceiling. A recall that waits two minutes for an optional model call has
+    // failed at its job; past this it degrades and searches the query verbatim.
+    "expansion_timeout_ms": 4000,
+    // Add bounded exact evidence paths as a third candidate arm. Candidates still
+    // pass through ordinary rank fusion, reranking, qualification, and budgeting.
+    "graph": true,
+    // Multiplied into the final score at assembly, not at search.
+    "rank": {
+      "knowledge": 1,
+      "source": 0.85,
+      "inference": 0.6
+    }
+  },
+
+  // ─── Watching ─────────────────────────────────────────────────────────────
+  "watch": {
+    "enabled": true,
+    // FSEvents coalesces; this debounce collapses an editor's write storm.
+    "debounce_ms": 400,
+    // The correctness path. FSEvents can drop events after sleep/wake or a
+    // large sync, so a periodic stat sweep is the backstop, not the watcher.
+    "sweep_interval_ms": 300000,
+    // Full hash sweep — catches a sync client or restore that preserved mtime.
+    "verify_interval_ms": 3600000
+  },
+
+  // ─── The maintenance cycle ────────────────────────────────────────────────
+  // Retain runs per turn; observe, reflect and curate run in `akno dream`.
+  // Phases are independent and each is safe to re-run.
+  //
+  // A **mission** appends emphasis to a fixed system prompt and never replaces
+  // it. That is a guardrail, not a convenience: every rule that keeps an
+  // inference engine honest lives in the fixed part, and a replaceable prompt is
+  // how they all get lost at once.
+  "maintenance": {
+    // A named profile is the authority ceiling for the complete scheduled cycle:
+    // audit plans only, review waits for a human, autonomous uses the separate curator
+    // and applies accepted work. New installations start in audit until the owner chooses
+    // a more authoritative profile.
+    // In a full named-profile/policy run, every phase plan is sealed before automatic apply.
+    "profile": "audit",
+    // Optional per-class authority: off, audit, review, or auto. Omitted classes
+    // inherit the profile and explicit values may only lower it.
+    "policies": {},
+    // Cumulative apply ceilings shared by plan-backed observe, reflect, curate, and adopt
+    // in one invocation.
+    // Planning remains complete; an indivisible item that would cross a ceiling
+    // stays proposed with a typed budget_exhausted reason for a later run.
+    "limits": {
+      "max_items": 30,
+      "max_files_changed": 40,
+      "max_bytes_written": 500000,
+      "max_high_risk_items": 3
+    },
+    // Terminal plans keep exact private operations and evidence for short-term review,
+    // then retain only compact decisions, hashes, and verification receipts. Active,
+    // review, apply, and recovery states never expire through this policy.
+    "plan_retention": {
+      "payload_days": 30,
+      "receipt_days": 180
+    },
+    // The model the cycle uses, when it should not be the one indexing uses.
+    // Not a role of its own — the same capability as `derive`, pointed somewhere
+    // else for the one caller that runs unattended.
+    //
+    // This is worth setting. Measured on a real 223-page base: the observe tier
+    // produced 15 candidates worth about four with a local 3B, and 8 candidates
+    // with no guardrail violations at all with a strong model. A knowledge base
+    // that wants a good model once a night should not thereby send every recall
+    // expansion to a paid API.
+    //
+    //   "model": { "provider": "openai", "id": "gpt-5.6" }
+    "model": null,
+    // Local macOS notifications for scheduled runs. "actionable" reports only
+    // review backlog, failed/incomplete work, persistent budget deferral, repeated
+    // model degradation, or a missed cycle. "all" also confirms quiet success.
+    // Page text, paths, diffs, prompts, and model responses are never included.
+    "notifications": "off",
+    // Retain is the `remember` op, available per-turn — the tier that needs
+    // to be fresh does not wait for a timer. `dream` does not re-run it.
+    // Write every run down — what was applied, what a guardrail refused, what was
+    // skipped and why — to <state_dir>/logs/dream.jsonl, one JSON object per run.
+    //
+    // Off by default on purpose. A log of inferences drawn from private notes is a
+    // second copy of the sensitive part, kept outside the notes. It is genuinely
+    // useful while you are deciding whether to trust the cycle; that is a decision
+    // for whoever owns the notes, not for a default.
+    "log_changes": false,
+
+    "retain": {
+      "enabled": true,
+      "mission": null,
+      // Optional exact page slug for durable claims that have no ordinary admitted destination.
+      // The page itself must allow remember integration, or its parent folder must explicitly
+      // allow creation. Reserved pages such as the event timeline are never valid fallbacks.
+      "fallback_page": null
+    },
+    // Combine repeated facts into stable patterns. Writes pages under
+    // `observations/` with `derived: true` and the evidence it used, appending
+    // only: a changed pattern gets a new dated line and nothing is deleted.
+    //
+    // Off by default from measurement, not caution. On a real 223-page knowledge
+    // base with a local 3B model, one run produced 18 candidate patterns of
+    // which about three were worth keeping — and every one of them would have
+    // been recalled later as truth. The guardrails hold; what they cannot do is
+    // make a small model insightful. Turn this on with a model you have watched
+    // produce patterns worth having, and read the first run with `--dry-run`.
+    "observe": {
+      "enabled": false,
+      "mission": null,
+      // Distinct source pages an observation needs. Two is the floor and the
+      // schema refuses less: one page agreeing with itself is not a pattern.
+      "min_evidence": 2,
+      // Subjects looked at per run, most recently touched first.
+      "max_subjects": 40
+    },
+    // Ships as an extension point, off by default. At a few hundred pages
+    // and a handful of events a month, a "pattern" is one coincidence away from
+    // noise. Switch it on when a knowledge base has the volume, not before.
+    "reflect": {
+      "enabled": false,
+      "mission": null
+    },
+    // Page-owned curation. Only knowledge pages with an explicit frontmatter
+    // `akno.management.dream` of `hygiene` or `synthesize` are candidates. Input
+    // fingerprints skip unchanged pages; synthesis also fingerprints linked evidence
+    // and conflicts, and an accepted preview reruns once when writes are enabled. Bounded
+    // events gain a journalled `akno.temporal` boundary; after it passes, only strong
+    // post-event evidence wakes one archival assessment instead of another planning pass.
+    // The draft is checked by a second model pass and deterministic guards.
+    // The profile/policy matrix controls durable exact plans for hygiene and synthesis
+    // pages, including atomic canonical-page splits, extraction of a reusable subject
+    // into an independent page, and exact-alias merge inside an eligible folder.
+    "curate": {
+      "verify": true,
+      "max_pages": 8,
+      // Structural operations are separately bounded across the whole run.
+      "max_splits": 3,
+      "max_extracts": 3,
+      // Merge is higher risk and therefore needs an explicit folder allowlist.
+      // Use ["*"] only when every synthesize-opted knowledge folder is eligible.
+      "max_merges": 2,
+      // Exact scalar type correction and explicitly routed max-depth relocation share this cap.
+      "max_rule_drifts": 20,
+      "merge_folders": [],
+      // "exact" uses aliases and conservative graph subjects. "semantic" additionally
+      // runs the qualified embedding prefilter and strict candidate classifier.
+      "merge_discovery": "exact",
+      "max_children_per_page": 2,
+      // Split only large canonical pages into substantial subordinate sections.
+      "split_after_bytes": 16384,
+      "split_section_bytes": 8192,
+      // Extract one reusable subject into an existing integrated-knowledge folder.
+      "extract_after_bytes": 8192,
+      "extract_section_bytes": 1024
+    },
+    // Give a document that no page owns a page of its own, beside the file, from
+    // the summary extraction already produced. Orphan text is directly recallable;
+    // adoption adds a browsable home, page metadata, and richer future organization.
+    // Honours a folder rule of `ingest: "file"`, which exists for exactly the case
+    // where a stub page per file would be noise — and never touches the file itself.
+    "adopt": {
+      // A folder of 500 unowned PDFs should not become 500 pages overnight before
+      // anyone has read the first report.
+      "max_pages": 20
+    },
+    // The thorough pass: facts on different pages that state different values
+    // for the same thing — which inline checking cannot see, because neither page
+    // is being written. Classification itself never rewrites a claim. When
+    // plan-backed curate is enabled, guarded contradiction items may represent
+    // or resolve the typed result on pages that explicitly allow synthesis.
+    "conflicts": {
+      "enabled": true,
+      // Ask a model whether a candidate pair really conflicts. Off leaves
+      // every candidate reported as `unverified`, which is honest and cheaper.
+      "verify": true,
+      // Include high-risk contradiction items in audit/review/auto curation plans.
+      // Model confidence cannot authorize supersession: the current claim must
+      // carry an explicit dated as-of/effective/from/since boundary, and every affected page
+      // must declare `dream: synthesize`. Qualification requires an exact scope phrase
+      // and the broad claim's exact value in a distinct sealed evidence claim.
+      "resolve": true,
+      "max_pairs": 40
+    },
+    // Broken links use the same durable plan lifecycle as curation and contradictions:
+    // exact evidence, curator or human decision, stale checks, one journal per item,
+    // and post-write verification. `links` includes them in curate plans. `enabled`
+    // keeps the report-only `repair` phase available for compatibility.
+    "repair": {
+      "enabled": false,
+      "links": true,
+      "max_changes": 25
+    }
+  },
+
+  // ─── Doors ────────────────────────────────────────────────────────────────
+  "server": {
+    // Unix socket, relative to state_dir. Filesystem permissions are the auth.
+    "socket": "akno.sock",
+    // Loopback HTTP for sandboxed or remote agents. Null = off.
+    "http": null,
+    // Ops an MCP caller may invoke. Trust is a parameter, not a property of the
+    // transport — the same code runs with different permissions. Add "adopt" to
+    // expose only the document-scoped, plan-backed filing action to an agent.
+    "mcp_allow": ["recall", "answer", "read", "list", "timeline", "context", "graph"]
+  },
+
+  // ─── Ingest ───────────────────────────────────────────────────────────────
+  "ingest": {
+    "max_file_mb": 25,
+    // Pages OCR'd before stopping. A 200-page scan need not be fully searchable to
+    // be findable, and the ingest report says how many were read. Measured on this
+    // hardware: ~0.6s per page through the Vision framework.
+    "max_ocr_pages": 12,
+    // The second naming guard: below this, the file keeps its name, gets no page, and is
+    // reported — rather than being given a confident wrong name. Renaming is the one
+    // destructive thing ingest does, so the bias is toward not doing it.
+    "name_confidence": 0.55,
+    // Keep the extracted text as `<file>.txt` beside the file it came from, so anything that
+    // is not Akno — a grep, an editor, a git diff, an agent with a folder and no socket —
+    // can read a scanned contract without OCRing it again. Akno itself never needs this:
+    // the text is indexed against the document and `read({document})` returns all of it.
+    //
+    // Off, because the folder is the user's and this is the only setting that would put a
+    // file next to every document on a first run. On, a rendition is recognised as the same
+    // document rather than a second one, so it costs no extra summary and returns no second
+    // hit — and one that was edited by hand is left alone rather than overwritten.
+    "text_rendition": false,
+    // Under this, the page beside the document already says everything the document does, and
+    // a second file is clutter. Roughly one chunk: below `index.chunk_target_chars`.
+    "text_rendition_min_chars": 1000,
+    // Executables and installers. Not a security boundary — Akno never runs what
+    // it ingests — but a `.dmg` filed as a memory is a mistake worth refusing.
+    "blocked_extensions": [
+      "exe",
+      "dll",
+      "so",
+      "dylib",
+      "app",
+      "pkg",
+      "dmg",
+      "msi",
+      "bat",
+      "cmd",
+      "com",
+      "scr",
+      "jar",
+      "sh",
+      "bash",
+      "zsh",
+      "ps1"
+    ]
+  },
+
+  // How long a deleted page or document is recoverable from trash.
+  "trash_retention_days": 30,
+
+  // ─── Rules ────────────────────────────────────────────────────────────────
+  // Glob-scoped, most-specific-wins. Empty by default: Akno ships no folder
+  // taxonomy. A knowledge base with no rules at all works — every page has the
+  // searchable `knowledge` role, but `remember` cannot inject facts until a page or
+  // folder explicitly sets `remember: "integrate"`. Rules at `<akno_path>/akno.jsonc`
+  // win over these, so they can travel with the notes.
+  //
+  // `route: true` is what turns a folder into an inbox: files dropped there are
+  // extracted, named, and *moved* to wherever they belong. It is the only place
+  // Akno moves files — a file dropped straight into `documents/` was put there
+  // on purpose. Empty here because automatic filing should be opt-in:
+  //
+  //   "inbox/**": { "ingest": "auto", "route": true }
+  // A max_depth rule remains diagnostic unless the same rule also names `relocate_to`.
+  // That explicit folder authorizes a byte-preserving, link-safe relocation; Akno never
+  // invents a destination from the depth or slug pattern alone.
+  "folders": {}
+}