faf-cli 7.12.0 → 7.13.0

package/dist/core/types.d.ts

@@ -60,6 +60,14 @@ export interface ScoreResult {
      * `inherited: true` per schema validation.
      */
     represents?: string;
+    /**
+     * True when the score is NOT KNOWN: an About Repo with no valid
+     * `about.source_score`. `score` is then -1 and `tier` is White only as a
+     * placeholder — neither is a result. Render it as "unknown" (—), never as a
+     * number or a percentage ("-1/100", "-1%"), and do not seal a receipt or
+     * attest it. Set only when true (absent on every calculated or inherited score).
+     */
+    unknown?: boolean;
 }
 /** Tier boundary info */
 export interface TierInfo {

package/dist/core/yaml-edit.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Document-preserving YAML edits — how faf changes a .faf or .fafm that is
+ * already on disk.
+ *
+ * The file is parsed with yaml's `parseDocument`, the change is made on the
+ * Document through its node APIs (`set` / `setIn` / `delete`), and only the
+ * text of the nodes that changed is rewritten. Every other byte stays as it
+ * was: comments, blank lines, key order, quoting, scalar source text (`1.10`,
+ * `0x1F90`, a 20-digit integer), anchors and aliases, unknown keys, CRLF line
+ * ends and a BOM.
+ *
+ * Safety net: the spliced text is parsed again and must hold the same data as
+ * the changed Document and serialise the same way (comments, styles, anchors;
+ * blank lines aside). If it does not (a shape the splicer does not handle),
+ * faf writes the Document's own serialisation instead — `toString({
+ * lineWidth: 0 })`, which still keeps comments, anchors, unknown keys and the
+ * source text of every number it did not change. A change that leaves the
+ * data as it was returns the original text untouched — even when that
+ * serialisation would differ — so callers skip the write.
+ */
+import { Document, YAMLMap, YAMLSeq, type DocumentOptions, type ParseOptions, type SchemaOptions } from 'yaml';
+type YamlOptions = ParseOptions & DocumentOptions & SchemaOptions;
+/** The result of {@link editYaml}. */
+export interface YamlEditResult {
+    /** The new text — the original text when nothing changed. */
+    text: string;
+    /** False when the change left the document as it was. */
+    changed: boolean;
+}
+/** Parse options for every document faf edits. */
+export declare const EDIT_OPTIONS: YamlOptions;
+/** Parse `src` for editing; a file that is not valid YAML is refused (an
+ *  Error whose `cause` is yaml's YAMLParseError, with its line). */
+export declare function parseForEdit(src: string, name: string): Document;
+/**
+ * Parse `text`, let `mutate` change the Document, and return the new text with
+ * every byte outside the changed nodes kept. `name` labels errors (a file that
+ * is not valid YAML is refused — nothing is guessed). When the change leaves
+ * the data as it was (the same values, whatever the nodes or their order),
+ * the original `text` is returned with `changed: false`.
+ */
+export declare function editYaml(text: string, mutate: (doc: Document) => void, name?: string): YamlEditResult;
+/** {@link editYaml}, also saying how the text was made: `spliced` is true when
+ *  only the changed nodes were rewritten, false when faf fell back to the
+ *  Document's own serialisation (or nothing changed). For tests. */
+export declare function editYamlDetailed(text: string, mutate: (doc: Document) => void, name?: string): YamlEditResult & {
+    spliced: boolean;
+};
+/** Deep equality of plain parsed values (mappings compared key by key). */
+export declare function sameJs(a: unknown, b: unknown): boolean;
+/** How {@link applyMapData} treats keys the data does not name. */
+export interface ApplyOptions {
+    /** Remove keys of a mapping that the data leaves out (or sets `undefined`).
+     *  Default false: a key the data does not mention stays exactly as it is. */
+    prune?: boolean;
+    /** Leave every alias (`*name`) as written, whatever the data holds there:
+     *  it is never expanded or replaced (see {@link keptAliases}). */
+    keepAliases?: boolean;
+}
+/**
+ * Set `node` to hold `value` with the fewest changes: a mapping is updated key
+ * by key, a list item by item (items still there are kept as they are), a
+ * scalar in place (its comment, quoting and position kept). Returns the node
+ * to store — `node` itself, or a new node when the shape changed.
+ */
+export declare function applyValue(doc: Document, node: unknown, value: unknown, opts?: ApplyOptions): unknown;
+/** Make `map` hold `data`: changed keys updated in place, new keys appended in
+ *  `data`'s order. Keys `data` leaves out stay, unless `prune` is set. */
+export declare function applyMapData(doc: Document, map: YAMLMap, data: Record<string, unknown>, opts?: ApplyOptions): void;
+/**
+ * Merge `data` into `map`, whose parsed value (the file as it was read) is
+ * `before`, writing only the paths where `data` differs from `before`:
+ *   - a key whose value in `data` equals its value in `before` is not touched
+ *     — its node stays exactly as written, so an alias (`summary: *g`), a
+ *     merge key or a comment on it survives even when `data` spells out the
+ *     value the alias read as (a stale copy never replaces a live `*alias`);
+ *   - a changed mapping is merged key by key the same way;
+ *   - any other changed value is set with {@link applyValue};
+ *   - an alias (`stack: *base`) is never replaced or expanded, at any depth:
+ *     it stays as written, and a change `data` makes under it is not written
+ *     ({@link keptAliases} lists those paths);
+ *   - keys `data` leaves out (or sets `undefined`) stay; new keys are appended.
+ * This is how writeFaf applies full .faf data to an existing file.
+ */
+export declare function mergeData(doc: Document, map: YAMLMap, before: unknown, data: Record<string, unknown>): void;
+/** An alias faf left as written: where it is (`stack`, `key_files.2`) and
+ *  what it says (`*base`). With `kind: 'anchor'` the path holds an anchor an
+ *  alias reads (`alias` then says `&name`): `faf auto` would have filled it,
+ *  which would change every alias that reads it, so it is left as written. */
+export interface KeptAlias {
+    path: string;
+    alias: string;
+    kind?: 'alias' | 'anchor';
+}
+/** The aliases in `doc` where `data` changed the value the file held
+ *  (`before`) and the alias does not read as the new value — a change under
+ *  an alias that faf did not write, because it never replaces or expands an
+ *  alias. A value `data` only repeats (a stale copy of what the alias read
+ *  as) is not a change. */
+export declare function keptAliases(doc: Document, data: unknown, before: unknown): KeptAlias[];
+/**
+ * Put back every alias of `before` that `after` (the same Document, changed)
+ * holds something else in place of: faf never replaces an alias, so that
+ * path keeps the file's `*name` and its change is not written. A key the
+ * change removed stays removed. Returns the aliases put back.
+ */
+export declare function restoreAliases(before: Document, after: Document): KeptAlias[];
+/**
+ * Put back every node of `before` that carries an anchor an alias reads
+ * (`frontend: &x None` while `ui_library: *x`) and that `after` (the same
+ * Document, changed) holds something else in place of: a fill there would
+ * change the value of every alias that reads it, so faf leaves the node as
+ * written and its change is not written. Returns those paths (`kind:
+ * 'anchor'`, `alias` saying `&name`).
+ */
+export declare function restoreAnchors(before: Document, after: Document): KeptAlias[];
+/**
+ * Apply the change from `before` to `after` to `node`, touching nothing the
+ * change does not name: for mappings, only keys added, removed or changed
+ * between the two are written — a key in the file that neither side mentions
+ * stays as it is. Returns the node to store.
+ */
+export declare function applyChange(doc: Document, node: unknown, before: unknown, after: unknown): unknown;
+/** The mapping at `path` (created when absent or empty). Throws when something
+ *  else is there — faf never replaces a scalar or a list to make room. */
+export declare function mapAt(doc: Document, path: readonly string[], name: string): YAMLMap;
+/**
+ * Apply the change `before` → `after` at `path` (see {@link applyChange}).
+ * The parent mapping is created when absent; `after === undefined` removes the
+ * key. Nothing is touched when the two are equal.
+ */
+export declare function changeAt(doc: Document, path: readonly string[], before: unknown, after: unknown, name: string): void;
+/** The list at `path`, created (as an empty list) when absent or empty.
+ *  Throws when something else is there. */
+export declare function seqAt(doc: Document, path: readonly string[], name: string): YAMLSeq;
+export {};

package/dist/detect/assemble.d.ts

@@ -15,11 +15,55 @@ export declare function assembleFreshFaf(dir: string): Record<string, unknown>;
  * consumers (faf-mcp's faf_auto) compose it instead of re-deriving it and
  * drifting (they used to merge assembleFreshFaf's slotignore'd output over the
  * existing file, losing interrogated facts such as a docker-compose Redis).
+ *
+ * Shape: `existing` must be a mapping (an empty document, null, reads as `{}`);
+ * a scalar or a list throws rather than being spread into character keys. A
+ * non-null scalar `project:` (older writers stored `project: <name>`) is lifted
+ * to `{ name: String(value) }`, so the name is kept and the rest can be filled.
+ *
+ * Words typed into a slot — a typed none (`None` / `N/A` / `not applicable`)
+ * or any other placeholder word (`unknown`, `"null"`), any case — are an
+ * empty slot: they score 0 until filled.
+ *   - In a tech slot (every slot but the 6Ws) a repo fact fills it: "if it's
+ *     a fact, fill the slot". With no fact the words stay exactly as the file
+ *     has them, comment included; faf never writes `''` over them.
+ *   - In a tech slot the file's app-type (`project.type`) leaves out, the
+ *     app-type's decision is the fact: with no repo fact, the slot becomes
+ *     `slotignored` (shown as N/A) in place of the words, an empty value or a
+ *     placeholder. A real value there is kept. `slotignored` comes only from
+ *     the app-type — in a slot the app-type uses, it is never written, even
+ *     when detection reads the repo as another type; such a slot gets the
+ *     repo's fact for it instead (`runtime: Go` from go.mod), or keeps what
+ *     it had. A `project.type` faf does not know decides nothing, and neither
+ *     does the `library` detection falls back to when the repo has no
+ *     classifying signal.
+ *   - In a 6W (`human_context.*`) the words are the person's: auto never
+ *     replaces them (`faf go` asks).
+ * A slot that says `slotignored` under either of its names (`stack.db` for
+ * `stack.database`) gets no detected value under either. A slot the file
+ * names only by its Mk4 name (`stack.db`) keeps that name: faf adds no
+ * on-wire twin (`stack.database`), and a repo fact fills the name the file
+ * uses.
+ *
+ * The result is marked as a fill: writeFaf leaves a node with an anchor that
+ * an alias reads as written (`frontend: &x None` with `ui_library: *x`) —
+ * filling it would change every alias — and reports it like a kept alias.
  */
 export declare function updateExistingFaf(dir: string, existing: Record<string, unknown>): Record<string, unknown>;
-/** Fill empty/placeholder slots in `target` with values from `source`.
- *  `target` wins when its slot is non-empty. Empty here is per `isPlaceholder`
- *  (covers '', null, undefined, and known placeholder strings) — this is what
- *  lets interrogated/detected values overwrite the empty-string defaults that
- *  detectStack writes to human_context. */
+/** Fill empty slots in `target` with values from `source`. `target` wins
+ *  when its slot is non-empty. Empty here is '', null, undefined, an empty
+ *  list or mapping — this is what lets interrogated/detected values overwrite
+ *  the empty-string defaults that detectStack writes to human_context.
+ *
+ *  Typed words — a typed none (`None`, `N/A`, `not applicable`) or any other
+ *  placeholder word (`unknown`, `"null"`), any case — are an empty slot, but
+ *  only a fact replaces them: in a tech slot (every slot but the 6Ws, under
+ *  either of its names) a source value that is real content — not empty, not
+ *  a placeholder, not `slotignored` — fills it. Anything else leaves the
+ *  words exactly as they are: no fact, a 6W (`human_context.*`, the
+ *  person's), or a place that is not a slot.
+ *
+ *  A `_meta` the target already carries (the user's own) is never filled
+ *  over: faf's runtime `_meta` from `source` is merged only into a target
+ *  without one. */
 export declare function fillEmpties(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;

package/dist/detect/git-repo.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The pure parts of `faf git` — no git, no network, no child process.
+ *
+ * `faf git <url>` validates the URL, clones the repo into a temp folder, and
+ * authors a fresh .faf from it with the same pipeline `faf auto` runs. The
+ * clone is the only step that runs git, and it stays in the CLI command. The
+ * rest lives here so consumers (claude-faf-mcp's faf_git, faf-mcp) compose it:
+ * they fetch the repo their own way, then call `authorFafFromRepo(dir)` and get
+ * the same .faf `faf git` would write — canonical keys, scored by faf's own
+ * scorer — instead of a hand-rolled extractor with its own schema.
+ */
+import type { FafData } from '../core/types.js';
+/**
+ * Validate + normalize a GitHub repo reference into a safe clone URL.
+ *
+ * A `faf git` URL is an untrusted CLI/MCP argument. This gate rejects any
+ * shell metacharacter or whitespace, and only ever returns a URL built from a
+ * strict allowlist pattern — defense in depth alongside the no-shell
+ * `execFileSync` clone (which already makes argument injection structurally
+ * impossible). Nothing carrying a metacharacter or control char ever reaches
+ * `git`: metachars are caught here; anything else fails the allowlist below.
+ *
+ * Accepts:
+ *   owner/repo · github.com/owner/repo · https://github.com/owner/repo
+ *   (optional `.git` suffix, optional trailing slash; full http(s) URLs to
+ *    any host pass through with a single `.git` suffix)
+ *
+ * Throws on empty / malformed / unsafe input.
+ */
+export declare function normalizeGitUrl(input: string): string;
+/** The repo name from a normalized clone URL: .../owner/repo.git → repo. */
+export declare function repoNameFromUrl(repoUrl: string): string;
+export interface AuthorFafFromRepoOptions {
+    /** The repo's URL (a clone URL, or any form `normalizeGitUrl` accepts).
+     *  When the fetched folder gives the project no name of its own (no
+     *  package.json name), the project is named after the repo instead of the
+     *  folder it was fetched into. */
+    repoUrl?: string;
+}
+/**
+ * Author a fresh .faf, as data, from a repo that is already on disk — the
+ * function form of `faf git`. Pass the folder you cloned or unpacked the repo
+ * into. Runs the full `faf auto` pipeline (detect → interrogate → slotignore →
+ * Turbo-Cat → Relentless) on that folder only, and returns the FafData —
+ * nothing is written, nothing is fetched, no git is run.
+ *
+ * Write it with `writeFaf` and score the written text with `scoreFafYaml`, so
+ * the score you report is the one faf reports.
+ */
+export declare function authorFafFromRepo(dir: string, opts?: AuthorFafFromRepoOptions): FafData;

package/dist/detect/scanner.d.ts

@@ -49,7 +49,8 @@ export declare function detectPolyglotLanguage(dir: string): string | null;
 export declare function readPackageJson(dir: string): PackageJson | null;
 /** Detect frameworks in a directory */
 export declare function detectFrameworks(dir: string): DetectedFramework[];
-/** Detect the primary language of a project */
+/** Detect the primary language of a project from its manifests — `''` when
+ *  there is no evidence. */
 export declare function detectLanguage(dir: string): string;
 /** Project-type detection result + rationale (the #found list).
  *  Each `found` entry is a human-readable signal that contributed to the
@@ -72,13 +73,17 @@ export declare function detectProjectTypeWithRationale(dir: string): ProjectType
  *  returns just the type string. New code should prefer
  *  `detectProjectTypeWithRationale` to access the `#found` rationale. */
 export declare function detectProjectType(dir: string): string;
-/** Detect the runtime */
+/** Detect the runtime from a runtime file or manifest — `''` when there is
+ *  no evidence. */
 export declare function detectRuntime(dir: string): string;
-/** Detect package manager */
+/** Detect the package manager from repo facts — a manifest that implies one,
+ *  package.json's `packageManager` field, then a lockfile. `''` when there is
+ *  no evidence: a package.json alone does not say which manager installs it. */
 export declare function detectPackageManager(dir: string): string;
 /** Detect CI/CD */
 export declare function detectCicd(dir: string): string | null;
-/** Detect hosting platform */
+/** Detect hosting platform — from a platform's own config file. A bare
+ *  Dockerfile is not one: it shows a container build, not where the app runs. */
 export declare function detectHosting(dir: string): string | null;
 /** Detect SvelteKit adapter from svelte.config.js */
 export declare function detectSvelteAdapter(dir: string): string | null;

package/dist/detect/stack.d.ts

@@ -1,3 +1,16 @@
 import type { FafData } from '../core/types.js';
-/** Auto-detect project stack and generate .faf data */
+/** Detect the project stack from repo facts and build .faf data. A slot with
+ *  no evidence is left empty (`''`) — never a default. */
 export declare function detectStack(dir: string): FafData;
+/**
+ * {@link detectStack}'s data, and `facts`: the repo's fact for every stack
+ * slot (by field — `runtime`, `database`), whatever the app-type — `''` when
+ * the repo shows none. detectStack marks a slot its detected type leaves out
+ * `slotignored`; `faf auto` fills such a slot from `facts` when the file's own
+ * type uses it (a `backend` project whose repo reads as a CLI still gets
+ * `runtime: Go` from go.mod).
+ */
+export declare function detectStackWithFacts(dir: string): {
+    data: FafData;
+    facts: Record<string, string>;
+};

package/dist/detect/turbo-cat-knowledge.d.ts

@@ -28,6 +28,16 @@
  * 😽 We are the FORMAT FREAKS - Quality over Quantity!
  * 🏆 199 formats - CHAMPIONSHIP GRADE FORMAT DETECTION
  */
+/**
+ * A slot value here must name what the file itself proves, in a slot that
+ * value fills: `vercel.json` → hosting Vercel; `Dockerfile` → no hosting (it
+ * shows a container build, not where the app runs); `jest.config.js` →
+ * nothing for CI/CD (Jest is a test runner, not a pipeline). No generic words ('Cloud',
+ * 'Containerized', 'API Server'), no language in a framework or backend slot,
+ * and no `runtime: Node.js` from a framework config alone — package.json is
+ * that fact, and detectRuntime reads it. `faf auto` writes these values into
+ * project.faf, so a value that is not a fact about the repo is a guess.
+ */
 export interface FormatKnowledge {
     frameworks: string[];
     slots: Partial<ContextSlots>;

package/dist/detect/turbo-cat.d.ts

@@ -4,8 +4,12 @@
  * manifest interrogation the v6.0 rewrite narrowed to README+Cargo+package.json.
  *
  * v6-native sync port (the v5 engine was async; sync integrates cleanly with
- * `auto`). Two-layer: (1A) config files walking up to the monorepo .git
- * boundary, (1B) source extensions; priority-wins slot recommendations.
+ * `auto`). Two-layer: (1A) config files in the project directory itself,
+ * (1B) source extensions below it; priority-wins slot recommendations.
+ *
+ * Boundary: detection never looks above the project directory. A parent's
+ * tsconfig.json, Cargo.toml or vercel.json is another project's evidence —
+ * a monorepo package, a subfolder or a new folder under ~ must not inherit it.
  *
  * Used as the LOWEST-precedence filler in `auto`: v6's specific detection wins;
  * Turbo-Cat fills only the slots still empty (esp. non-npm stacks).

package/dist/fafm/index.d.ts

@@ -1,4 +1,5 @@
 /** .fafm knowledge-profile library (TS) — INTEROP with claude-fafm-sdk 1.0 */
 export { PRIORITY_ORDER, PRIORITY_RANK, KNOWLEDGE_TYPES, type Fact, type Priority, type Profile, type SoulDoc, } from './types.js';
 export { Soul, utcNow, canonicalPriority, factFromObj, factToObj, } from './soul.js';
+export type { RecallOptions } from './soul.js';
 export { fromClaudeDir, DEFAULT_SKIP } from './from-claude-dir.js';

package/dist/fafm/soul.d.ts

@@ -1,12 +1,27 @@
 /**
  * Soul — local .fafm model (TS mirror of claude-fafm-sdk 1.0 Soul).
  * INTEROP: load/save fidelity, residual preserve, recall SoT.
+ *
+ * A soul loaded from a file keeps that file's text. `save` writes only what
+ * changed since the load (or the last save) into it — through the YAML
+ * Document, so comments, key order, quoting, the `version`, a missing
+ * `profile`, a hand-kept `index` and every unknown key stay as they were.
+ * Known keys faf does not model in the shape the file has them (a `facts` or
+ * `index` written as a mapping, `sessions` as a mapping, …) are kept verbatim;
+ * a change that would have to rewrite one is refused, with nothing written.
  */
 import { type Fact, type SoulDoc } from './types.js';
 export declare function utcNow(): string;
 export declare function canonicalPriority(p: string | null | undefined): string;
 export declare function factFromObj(obj: unknown): Fact;
 export declare function factToObj(f: Fact): unknown;
+/** Filters for {@link Soul.recall}. */
+export interface RecallOptions {
+    tags?: string[];
+    type?: string;
+    minPriority?: string;
+    limit?: number | null;
+}
 export declare class Soul {
     namepoint: string;
     profile: string;
@@ -21,6 +36,20 @@ export declare class Soul {
     private _custom;
     private _extra;
     private _memoryExtra;
+    private _version;
+    /** The file the soul was loaded from or last saved to. Undefined while the
+     *  soul was made with no file (in memory, not saved yet): its first save
+     *  then refuses a file already at the path — one that appeared since the
+     *  caller found none — unless `replace`. */
+    private _origin;
+    /** Each loaded fact's item position in the file's memory.facts. */
+    private _factAt;
+    /** The index was faf-derived when the soul was loaded (or made, or last
+     *  saved) — the default save keeps it in step with the facts. */
+    private _indexDerived;
+    /** The index as it was then: an index changed in memory since is the
+     *  caller's, and the default save leaves it as it is. */
+    private _indexAtRecord;
     constructor(namepoint: string, opts?: {
         profile?: string;
         facts?: Fact[];
@@ -40,18 +69,89 @@ export declare class Soul {
     get custom(): Record<string, unknown>;
     get extra(): Record<string, unknown>;
     get memoryExtra(): Record<string, unknown>;
+    /**
+     * Load a soul. The root must be a mapping (anything else is refused). Known
+     * keys in a shape faf does not model — `memory.facts` or `index` written as
+     * a mapping, `memory.sessions` as a mapping, `memory.preferences` as a list,
+     * `memory` itself as a list — load as empty and stay in the file verbatim;
+     * so do list items in `memory.facts` that are not facts.
+     */
     static load(path: string): Soul;
+    private static fromText;
+    /** Note whether the index is faf-derived now (at load, and after a save). */
+    private recordIndex;
+    /** Take a fact read from item `i` of the file's memory.facts. */
+    private adopt;
     static fromFile(path: string): Soul;
     toDoc(): SoulDoc;
     toYaml(): string;
+    /** The index faf derives from the facts (INTEROP §5 formula,
+     *  `${id ?? '?'} — ${text[:width]}` per fact) — without changing the soul. */
+    derivedIndex(width?: number): string[];
+    /** True when the stored index is exactly the one faf derives from the facts
+     *  (so faf wrote it, and may rewrite it). A hand-kept index is not. */
+    indexIsDerived(width?: number): boolean;
     rebuildIndex(width?: number): string[];
+    /**
+     * Write the soul — atomically (a failure leaves the original as it was)
+     * and never through a link that leaves the folder or dangles.
+     *
+     * A soul loaded from a file is written as that file's text with only what
+     * changed since the load (or the last save) edited into it; a save that
+     * changes nothing writes nothing.
+     *
+     * The index: `reindex: true` rebuilds it from the facts, `reindex: false`
+     * keeps it as it is. Left out, the index is rebuilt only when it was
+     * faf-derived — {@link indexIsDerived} when the soul was loaded or last
+     * saved; a new soul counts as derived unless it was given an index of its
+     * own — and has not been changed in memory since. A hand-kept index is
+     * never touched.
+     * Refused, with nothing written: a change to a known key the file holds in
+     * a shape faf does not model (adding a fact to `memory.facts` written as a
+     * mapping, say); a save over the file the soul was loaded from (or last
+     * saved to) when that file changed on disk since — SafePathError `changed`,
+     * so an edit made meanwhile is never written over; and a save of a soul
+     * made with no file (or to a path it was not loaded from) when a file is
+     * already there — the same `changed` refusal, so a soul.fafm that appeared
+     * after the caller found none is kept. `replace: true` is the explicit
+     * overwrite of such a file (`faf memory convert --force`).
+     */
     save(path: string, opts?: {
         reindex?: boolean;
+        replace?: boolean;
     }): string;
     toFile(path: string, opts?: {
         reindex?: boolean;
+        replace?: boolean;
     }): string;
+    /** After a save: the written text (at `real`) is the new origin. */
+    private settle;
+    /** The soul's modelled state as plain values. */
+    private state;
+    /** Refuse a change that would rewrite a key kept verbatim. */
+    private static refuse;
+    /** Edit the loaded Document with what changed since `origin.base`; returns
+     *  each fact's item position in memory.facts afterwards. */
+    private applyTo;
+    private applyMemory;
+    /** Which facts are still at their place in the file, and which are new.
+     *  Kept facts must be in the file's order, new ones after them. */
+    private sortFacts;
+    /** Facts: changed facts are edited where they are (only the fields that
+     *  changed), deleted ones removed, new ones appended. List items that are
+     *  not facts are never touched. */
+    private applyFacts;
+    /** Insert or overwrite a Fact by id, preserving every field it carries (its
+     *  timestamp included) — the INTEROP merge primitive: on an existing id the
+     *  whole Fact is replaced. `etch` merges instead. */
     add(fact: Fact): Fact;
+    /**
+     * Write a fact. With an `id` that is already in the soul, the fact is
+     * updated in place: the text and timestamp are new, and of the other fields
+     * only those passed here change — links, source, tags, type, priority and
+     * any extra fields the fact carries are kept (a priority is never lowered
+     * unless one is passed). Otherwise the fact is appended.
+     */
     etch(text: string, opts?: {
         id?: string;
         type?: string;
@@ -60,12 +160,14 @@ export declare class Soul {
         links?: string[];
         source?: string;
     }): Fact;
-    recall(query?: string | null, opts?: {
-        tags?: string[];
-        type?: string;
-        minPriority?: string;
-        limit?: number | null;
-    }): Fact[];
+    /**
+     * Deterministic recall (INTEROP §6). Call it as `recall(query, filters)` or
+     * `recall({ query, ...filters })`. Bare-string facts are facts: their text
+     * is matched and returned like any other.
+     */
+    recall(query?: string | null | (RecallOptions & {
+        query?: string | null;
+    }), opts?: RecallOptions): Fact[];
     getFact(id: string): Fact | null;
     deleteFact(id: string): boolean;
 }

package/dist/index.d.ts

@@ -1,19 +1,25 @@
 export type { SlotState, SlotCategory, SlotDef, KernelScoreResult, ScoreResult, TierInfo, FafData, FafbInfo, DetectedFramework, FrameworkSignature, Signal, SignalType, } from './core/types.js';
 export { SLOTS, BASE_SLOTS, ENTERPRISE_SLOTS, SLOT_BY_PATH, slotsByCategory, PLACEHOLDERS, isPlaceholder } from './core/slots.js';
+export { EXPLICIT_NONE, SLOTIGNORED, isExplicitNone } from './core/slots.js';
 export { TIERS, getTier, getNextTier } from './core/tiers.js';
 export { FAF_HEX } from './ui/colors.js';
 export { enrichScore, scoreFafYaml } from './core/scorer.js';
+export { scoreText } from './core/scorer.js';
 export { validateFaf } from './core/schema.js';
 export { findFafFile, readFaf, readFafRaw } from './interop/faf.js';
+export { isNonProjectRoot } from './core/cwd-guard.js';
 export { computeDrift } from './core/drift.js';
 export type { DriftReport, DriftTarget, DriftStatus } from './core/drift.js';
 export { renderProjectHtml, generateProjectHtml, writeProjectHtml } from './interop/projecthtml.js';
-export { buildServerCard, generateServerCard, writeServerCard, fafContextBlock, registryMeta, registryName, REGISTRY_PUBLISHER_KEY, } from './interop/servercard.js';
-export type { ServerCardOptions } from './interop/servercard.js';
+export type { ProjectHtmlWriteOptions } from './interop/projecthtml.js';
+export { buildServerCard, generateServerCard, writeServerCard, fafContextBlock, registryMeta, registryName, registryTitle, REGISTRY_PUBLISHER_KEY, } from './interop/servercard.js';
+export type { ServerCardOptions, CardWriteOptions } from './interop/servercard.js';
+export { patchServerJson } from './interop/servercard.js';
+export type { ServerJsonIdentity } from './interop/servercard.js';
 export { projectCards, readFafa, findFafaFile, buildA2ACard, generateA2ACard, upsertCatalog, A2A_CONTEXT_URI, } from './interop/cards.js';
 export type { FafaDoc, CardTarget, ProjectedCards } from './interop/cards.js';
 export { Soul as FafmSoul, fromClaudeDir, canonicalPriority, utcNow, PRIORITY_ORDER, PRIORITY_RANK, KNOWLEDGE_TYPES, } from './fafm/index.js';
-export type { Fact as FafmFact, SoulDoc, Profile as FafmProfile } from './fafm/index.js';
+export type { Fact as FafmFact, SoulDoc, Profile as FafmProfile, RecallOptions as FafmRecallOptions } from './fafm/index.js';
 export type { InterviewQuestion, InterviewOption, HumanSlotPath, SourcedSlotPath, GoalSeed, TableOf8, TableOf8Row, BoxStatus } from './core/interview.js';
 export { INTERVIEW, SIX_WS_INTERVIEW, STACK_INTERVIEW, INTERVIEW_BY_PATH, INTERVIEW_PATHS, INTERVIEW_VERSION, questionForSlot, interviewForMissing, seedSixWsFromGoal, buildTableOf8, } from './core/interview.js';
 export type { LoopStatus, LoopGaps, LoopVerdict, LoopRunStatus, LoopDeps, LoopRunOptions, LoopRunResult } from './core/loop.js';
@@ -25,6 +31,10 @@ export type { TurboCatResult, DiscoveredFormat } from './detect/turbo-cat.js';
 export { relentlessContext, relentlessContextDetailed } from './detect/relentless.js';
 export type { SeededContext, SeededContextDetailed, SourcedValue } from './detect/relentless.js';
 export { assembleFreshFaf, updateExistingFaf, fillEmpties } from './detect/assemble.js';
+export { normalizeGitUrl, repoNameFromUrl, authorFafFromRepo } from './detect/git-repo.js';
+export type { AuthorFafFromRepoOptions } from './detect/git-repo.js';
+export { FafDNAManager } from './core/faf-dna.js';
+export type { FafDNA, BirthCertificate, VersionEntry, Milestone } from './core/faf-dna.js';
 export { renderAgentsMd, writeAgentsMd } from './interop/agents.js';
 export { renderGeminiMd, writeGeminiMd } from './interop/gemini.js';
 export { renderCursorrules, writeCursorrules } from './interop/cursorrules.js';
@@ -32,6 +42,17 @@ export { renderCopilotInstructions, writeCopilotInstructions } from './interop/c
 export { renderClaudeMd, writeClaudeMd, readClaudeMd, parseClaudeMd, fafMetaTag } from './interop/claude.js';
 export type { FafMetaOpts } from './interop/claude.js';
 export { injectFafBlock, findFafBlock, FAF_START, FAF_END } from './interop/inject.js';
+export type { InjectOptions } from './interop/inject.js';
+export { legacyStampNote, legacyStampNoteAt } from './interop/inject.js';
+export { claudeProjectId, claudeProjectRoot, resolveClaudeMemoryDir, resolveClaudeMemoryPath, renderClaudeMemory, writeClaudeMemory, claudeMemoryStatus, } from './interop/claude-memory.js';
+export type { ClaudeMemoryOptions, ClaudeMemoryResult, ClaudeMemoryAction, ClaudeMemoryStatus } from './interop/claude-memory.js';
+export { resolveInside, safeWriteFile, SafePathError } from './core/safe-write.js';
+export { readUtf8 } from './core/safe-write.js';
+export type { ResolveInsideOptions, SafeWriteOptions, SafePathReason } from './core/safe-write.js';
+export { safeReplaceOwned, makeDirInside, safeUnlink } from './core/safe-write.js';
+export type { ReplaceOwnedOptions } from './core/safe-write.js';
 export { enrichFromRepo } from './detect/enrich.js';
 export { serializeFaf, writeFaf } from './interop/faf.js';
+export { updateFafFile } from './interop/faf.js';
+export type { UpdateFafResult, WriteFafOptions, KeptAlias } from './interop/faf.js';
 export * as kernel from './wasm/kernel.js';