faf-cli 7.12.0 → 7.13.0

package/dist/interop/cards.d.ts

@@ -1,4 +1,5 @@
 import type { FafData } from '../core/types.js';
+import { type RenderedResult } from '../core/render-hash.js';
 import { type ServerCardOptions } from './servercard.js';
 /** A2A extension URI — dereference, not the MCP `_meta` key `one.faf/context`. */
 export declare const A2A_CONTEXT_URI = "https://faf.one/context";
@@ -111,9 +112,24 @@ export declare function buildA2ACard(fafa: FafaDoc, faf: FafData, opts?: Project
 /** @deprecated Use {@link buildA2ACard}. Removed in the next major. */
 export declare const generateA2ACard: typeof buildA2ACard;
 export declare function catalogEntriesFor(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): CatalogEntry[];
-/** Upsert projector entries into an existing catalog. Leaves unknown rows alone.
- *  On match, only url / type / updatedAt move — host copy (title, tags) stays. */
+/** Upsert projector entries into an existing catalog. Leaves every other row
+ *  alone: a row is faf's only when its identifier is exactly faf's (never by
+ *  type or URL). On match, only url / type / updatedAt move — host copy
+ *  (title, tags) stays; any other faf row is appended. */
 export declare function upsertCatalog(existing: AiCatalog | undefined, incoming: CatalogEntry[]): AiCatalog;
+/**
+ * {@link upsertCatalog} as a text edit of the catalog's JSON: faf's own rows
+ * (identifier exactly faf's) get their url / type / updatedAt values changed
+ * in place, faf's other rows are appended after the last entry, and every
+ * other byte — your rows, their order and layout, other keys — stays. With no
+ * text (no catalog yet) a new catalog is returned. Throws a JsonEditError,
+ * changing nothing, when the catalog cannot be edited that way (not a JSON
+ * object, `entries` not an array, faf's row there twice, …).
+ */
+export declare function upsertCatalogText(text: string | null, incoming: CatalogEntry[]): {
+    text: string;
+    changed: boolean;
+};
 export declare function projectCards(input: {
     faf: FafData;
     fafa?: FafaDoc;
@@ -122,5 +138,38 @@ export declare function projectCards(input: {
 }): ProjectedCards;
 /** Byte-identical context block on every emitted door. */
 export declare function assertSameBlock(cards: ProjectedCards): void;
-export declare function writeJson(path: string, value: unknown): void;
+/** True when `bytes` are an A2A Agent Card faf wrote: JSON whose
+ *  `capabilities.extensions` carry the FAF context extension
+ *  ({@link A2A_CONTEXT_URI}), as every card faf has written does. */
+export declare function hasA2ACardMark(bytes: Uint8Array): boolean;
+/** True when `bytes` carry any of faf's card marks: the MCP Server Card's
+ *  `_meta["one.faf/context"]`, a registry server.json's publisher-provided
+ *  `one.faf/context`, or the A2A card's FAF context extension. */
+export declare function hasFafCardMark(bytes: Uint8Array): boolean;
+/** Options for {@link writeJson}. */
+export interface WriteJsonOptions {
+    /** True when the bytes already at the path carry faf's older mark (a file
+     *  faf wrote before render hashes). Default: one of faf's card marks
+     *  ({@link hasFafCardMark}). */
+    owns?: (existing: Buffer) => boolean;
+    /** faf's mark in words, for the refusal. */
+    mark?: string;
+    /** Replace a file faf cannot prove it wrote anyway — the explicit overwrite (`--force`). */
+    force?: boolean;
+}
+/** Write `value` as JSON (2-space, final newline) with faf's render hash at
+ *  `_meta["one.faf/render"]` — atomically, and never through a link that
+ *  leaves `root` (default: the file's own folder) or dangles. The folder is
+ *  created when missing, never through a link that leaves `root`. A file
+ *  already there is replaced only when it is byte for byte what faf last wrote
+ *  (its render hash still fits); a file edited since, one without faf's mark,
+ *  or one from before 7.13 that is not exactly this JSON is refused
+ *  (SafePathError `not-owned`) and left byte for byte, unless `force`.
+ *  Returns what it did: `created`, `updated`, or `unchanged` (the file
+ *  already held exactly these bytes, and nothing was written). */
+export declare function writeJson(path: string, value: unknown, root?: string, write?: WriteJsonOptions): RenderedResult;
+/** True when `bytes` are JSON laid out exactly as faf writes it (2-space
+ *  JSON and a final newline), so re-writing it loses nothing: no hand
+ *  formatting, no repeated key, no number JSON cannot hold exactly. */
+export declare function isFafJsonLayout(bytes: Uint8Array): boolean;
 export declare function parseTargets(raw?: string): CardTarget[] | undefined;

package/dist/interop/claude-memory.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Claude Code auto-memory — the MEMORY.md Claude Code loads at the start of a
+ * session: `<config>/projects/<project-id>/memory/MEMORY.md`.
+ *
+ * Moved here from claude-faf-mcp (its tri-sync writer and path resolver) so
+ * every FAF tool shares one copy, with what the audit found fixed.
+ *
+ * WHERE the file is — Claude Code's own rule (mirrored from Claude Code 2.1.x):
+ *   - Project root: the canonical git root of the folder — the first folder at
+ *     or above it that has a `.git` (a folder or a file). A linked worktree
+ *     resolves to its main checkout, so every worktree shares one memory. A
+ *     folder that is not in git is its own root.
+ *   - Project id: that path with every character outside [a-zA-Z0-9] replaced
+ *     by `-` (so `/home/me/my_app` → `-home-me-my-app`). An id longer than
+ *     200 characters is cut to 200 and gets `-` plus a base-36 hash of the
+ *     full path.
+ *   - Base: CLAUDE_CODE_REMOTE_MEMORY_DIR when set, else Claude's config
+ *     folder: CLAUDE_CONFIG_DIR, else ~/.claude.
+ *   Not read: Claude Code's `autoMemoryDirectory` setting (or any other
+ *   override of the whole memory folder). When one is set, pass `memoryDir`.
+ *
+ * WHAT faf writes — one managed block (the same markers and injector as
+ * CLAUDE.md). Everything else in the file is Claude's and is kept byte for
+ * byte, CRLF line ends and a BOM included:
+ *   - no MEMORY.md             → the file is created with the block
+ *   - faf's block is there     → only the text between its marker lines changes
+ *   - claude-faf-mcp's earlier section (its `# Project Context (from
+ *     project.faf)` line through its `*This section is managed by tri-sync.`
+ *     line, both whole lines) → replaced in place by the block, once
+ *   - anything else            → the block goes on top; nothing is removed
+ * Markers match whole lines only (faf's own exactly), never substrings, and
+ * only outside fenced code, raw HTML blocks and multi-line HTML comments, as
+ * both CommonMark and a plain column-0 reading see them (a note that quotes
+ * the block or the old section is an example, not a marker; see inject.ts).
+ * When the block goes on top of a file whose older faf block sits in such a
+ * region, the result's warnings say so in one line. Only a missing file reads
+ * as "no file": any other read error is thrown and nothing is written, and a
+ * file that is not UTF-8 is refused. The write is atomic, is refused if the
+ * file changed on disk after faf read it, and a run that changes nothing
+ * writes nothing.
+ */
+import type { FafData } from '../core/types.js';
+export interface ClaudeMemoryOptions {
+    /** Claude Code's config folder. Default: CLAUDE_CODE_REMOTE_MEMORY_DIR,
+     *  else CLAUDE_CONFIG_DIR, else ~/.claude. */
+    configDir?: string;
+    /** The memory folder itself, when you know better than the rule (Claude
+     *  Code's `autoMemoryDirectory` setting, say). Skips the resolver. */
+    memoryDir?: string;
+}
+/** What `writeClaudeMemory` did. */
+export type ClaudeMemoryAction = 'created' | 'updated' | 'migrated' | 'added' | 'unchanged';
+export interface ClaudeMemoryResult {
+    /** The MEMORY.md (its real path). */
+    path: string;
+    /**
+     *  - `created`   there was no MEMORY.md; it now holds the block
+     *  - `updated`   faf's block was replaced in place
+     *  - `migrated`  claude-faf-mcp's earlier section was replaced by the block
+     *  - `added`     the file had neither; the block went on top
+     *  - `unchanged` the block was already exactly this; nothing was written
+     */
+    action: ClaudeMemoryAction;
+    /** False when nothing was written (`unchanged`). */
+    written: boolean;
+    /** Every byte outside faf's block is still in the file, in place — checked
+     *  by reading the file back after the write. */
+    preserved: boolean;
+    /** Lines in the file now. */
+    lines: number;
+    /** Plain-words notes (e.g. lines past the 200 Claude Code loads). */
+    warnings: string[];
+}
+/** What is in the MEMORY.md Claude Code loads for a project (read only). */
+export interface ClaudeMemoryStatus {
+    /** The MEMORY.md path (whether or not it exists). */
+    path: string;
+    exists: boolean;
+    /** Lines in the file. */
+    lines: number;
+    /** faf's block is in the file. */
+    hasBlock: boolean;
+    /** Lines in faf's block, its marker lines included (0 when there is none). */
+    blockLines: number;
+    /** claude-faf-mcp's earlier tri-sync section is in the file (the next write replaces it). */
+    hasLegacySection: boolean;
+    /** Non-blank lines outside faf's block: Claude's own notes. */
+    otherLines: number;
+    /** Plain-words notes (e.g. lines past the 200 Claude Code loads). */
+    warnings: string[];
+}
+/**
+ * Claude Code's folder name for a project path: every character outside
+ * [a-zA-Z0-9] becomes `-`; past 200 characters the id is cut to 200 and gets
+ * `-` plus a base-36 hash of the full path. `/home/me/my_app` → `-home-me-my-app`.
+ * Pass the project root (see {@link claudeProjectRoot}), not any folder.
+ */
+export declare function claudeProjectId(projectRoot: string): string;
+/**
+ * The project root Claude Code keys a folder's memory by: the canonical git
+ * root (a linked worktree → its main checkout), or the folder itself when it
+ * is not in git. The folder is resolved on disk first (links followed), as
+ * Claude Code sees its working folder; the result is NFC-normalized.
+ */
+export declare function claudeProjectRoot(dir: string): string;
+/** `<config>/projects/<project-id>/memory` for the project `dir` is in. */
+export declare function resolveClaudeMemoryDir(dir: string, opts?: ClaudeMemoryOptions): string;
+/** The MEMORY.md Claude Code loads for the project `dir` is in. */
+export declare function resolveClaudeMemoryPath(dir: string, opts?: ClaudeMemoryOptions): string;
+/**
+ * The block body faf keeps in MEMORY.md, from .faf data: a short project
+ * summary (name, goal, language, type), the filled stack slots, the 6 Ws,
+ * and up to 12 commands and key files. Kept short on purpose — Claude Code
+ * loads only the first 200 lines, and the rest of the file is Claude's.
+ */
+export declare function renderClaudeMemory(data: FafData): string;
+/**
+ * Read what is in the MEMORY.md Claude Code loads for the project `dir` is in:
+ * whether faf's block (or claude-faf-mcp's earlier section) is there, and how
+ * many lines are Claude's own. Reads only; never creates or writes anything.
+ * A file that exists but cannot be read throws.
+ */
+export declare function claudeMemoryStatus(dir: string, opts?: ClaudeMemoryOptions): ClaudeMemoryStatus;
+/**
+ * Write faf's block into the MEMORY.md Claude Code loads for the project `dir`
+ * is in (see the file header for the path rule and what is kept). Creates the
+ * memory folder when it is not there yet. Throws — having written nothing —
+ * when the file cannot be read (other than not existing), is not UTF-8, is a
+ * link that leaves the memory folder, changed on disk while faf was writing,
+ * cannot be written (the original is kept), or is one where faf cannot place
+ * its block where its next run finds it again (SafePathError `unplaceable`,
+ * the same one-line refusal as injectFafBlock).
+ */
+export declare function writeClaudeMemory(dir: string, data: FafData, opts?: ClaudeMemoryOptions): ClaudeMemoryResult;

package/dist/interop/claude.d.ts

@@ -1,5 +1,9 @@
 import type { FafData } from '../core/types.js';
-/** Read CLAUDE.md from a directory */
+/** Read CLAUDE.md from a directory. A CLAUDE.md link that leaves the
+ *  directory, or leads to a file that is not an AI context file, is refused
+ *  (SafePathError) and nothing is read; CLAUDE.md → AGENTS.md is read
+ *  through. A CLAUDE.md that is not UTF-8 is refused too (`faf sync --direction
+ *  pull` writes what it reads into project.faf). */
 export declare function readClaudeMd(dir: string): string | null;
 /** Write CLAUDE.md — non-destructive: injects/updates the faf block, preserves the rest. */
 export declare function writeClaudeMd(dir: string, content: string): void;

package/dist/interop/commonmark.d.ts

@@ -0,0 +1,144 @@
+/**
+ * CommonMark's block structure, line by line — just enough of it to say which
+ * lines Markdown shows as code, or hides in a raw HTML block or a multi-line
+ * comment. faf uses it to tell its own marker lines from marker examples.
+ *
+ * The algorithm is the reference implementation's (commonmark.js, spec 0.31):
+ * each line first continues the open containers (block quotes, list items —
+ * a list item's lines sit at its content column, a tab after the marker
+ * advancing to the next multiple of 4), then may open new blocks, then is
+ * added to the innermost open block or continues a paragraph lazily. Only
+ * what decides block structure is kept: no inline parsing, no link reference
+ * definitions, no tables.
+ *
+ * A reader made with `containers: false` reads every line at column 0 with no
+ * block quotes and no list items — the plain reading a text editor, an older
+ * faf or another tool may apply. faf takes a block as its own only when both
+ * readings agree (see inject.ts).
+ *
+ * What a line counts as hidden in:
+ *   - fenced code (its opening and closing lines included) and indented code;
+ *   - an HTML block of types 1-5 — <pre>/<script>/<style>/<textarea> up to the
+ *     closing tag, a comment up to `-->`, <?…?>, <!X…>, <![CDATA[…]]> — except
+ *     a comment that opens and closes on the one line (faf's own marker
+ *     lines are such comments);
+ *   - not an HTML block of types 6 or 7 (<div>, <details>, any lone tag): a
+ *     comment inside raw HTML is still a comment. No fence or other block
+ *     opens inside one until a blank line ends it.
+ *
+ * Speed: each line costs time in proportion to its length, however deep the
+ * nesting — the reader never re-reads the rest of a line per nesting level.
+ * Past MAX_OPEN_CONTAINERS open block quotes, lists and list items the reader
+ * stops reading (`tooDeep`): faf cannot say for sure where such a file's
+ * regions are, so the file is the user's — faf's block goes on top and every
+ * byte stays.
+ */
+/** More open block quotes, lists and list items than this, and a reader stops
+ *  reading (see {@link BlockReader.tooDeep}). */
+export declare const MAX_OPEN_CONTAINERS = 100;
+/** What hides a line: its region, as faf names it to the user. */
+export type HiddenIn = 'code fence' | 'indented code' | 'html' | 'comment' | `<${string}>`;
+/** Feeds a text line by line (terminators removed) and says which lines are hidden. */
+export declare class BlockReader {
+    private readonly containers;
+    private stack;
+    private ln;
+    private offset;
+    private column;
+    private nextNonspace;
+    private nextNonspaceColumn;
+    private indent;
+    private indented;
+    private blank;
+    private allClosed;
+    private matched;
+    private htmlStarted;
+    private hiddenIn;
+    /** Where the last whitespace scan of this line started (-1: none yet). */
+    private scannedFrom;
+    /** Per line, lazily: 1 where the rest of the line is a thematic break. */
+    private breaks;
+    private deep;
+    /** With a limit (see {@link overflowAt}): open containers allowed, and
+     *  where the line first opened one past it (-1: nowhere yet). */
+    private limit;
+    private overflow;
+    private readonly starts;
+    /** `containers: false` — the plain column-0 reading: no block quotes, no list items. */
+    constructor(containers?: boolean);
+    /** An independent copy, for trying lines out. */
+    clone(): BlockReader;
+    /**
+     * Where in `ln` a reader in this state would open a block quote, list or
+     * list item past `limit` open ones — the offset of that quote's `>` or that
+     * item's marker — or -1 when the line leaves at most `limit` open. This
+     * reader does not move: a copy reads the line.
+     */
+    overflowAt(ln: string, limit: number): number;
+    /** True once more than MAX_OPEN_CONTAINERS block quotes, lists and list
+     *  items were open at once. The reader then stops reading: what it says
+     *  about that line and every later one means nothing, and a caller treats
+     *  the file as one it cannot read for sure. */
+    get tooDeep(): boolean;
+    /** Read one line (no terminator). Returns what hides it, or null when it is shown as text. */
+    line(ln: string): HiddenIn | null;
+    /** The line that would close the region a column-0 line would now be hidden
+     *  in (a fence or an HTML block of types 1-5 at the top level), or null. */
+    closer(): string | null;
+    private get tip();
+    /** Step 1: the open containers the line continues. Returns the index of the
+     *  last one it continues, or -1 when it closed a fence. */
+    private continueContainers;
+    /** Step 2: the blocks the line opens, from the container at `index`. Returns the block the rest of the line goes to. */
+    private openBlocks;
+    /** A block just opened at `at` (`res` 1: a container): with a limit set,
+     *  remember the first place the line went past it (below the document
+     *  only containers are open when a container is added). */
+    private noteOverflow;
+    /** Step 3: the rest of the line goes to `block`. */
+    private addText;
+    private addHtmlLine;
+    /** Does the line continue the open block `b` (at `index`)? 0 yes, 1 no, 2 it closed a fence. */
+    private continues;
+    /** The document and a list always continue; a heading or a break never
+     *  does; a paragraph and an HTML block of type 6 or 7 end at a blank line. */
+    private continueOther;
+    private continueQuote;
+    private continueItem;
+    private continueFence;
+    private continueIndentedCode;
+    /** The character at the next non-space position ('' at the line's end). */
+    private get ch();
+    /** True when the rest of the line, from the next non-space position, is a
+     *  thematic break (see {@link thematicBreaks}; worked out once per line). */
+    private breakAhead;
+    private startQuote;
+    private startHeading;
+    private startFence;
+    private startHtml;
+    private startSetext;
+    private startBreak;
+    private startItem;
+    private startIndentedCode;
+    /** The list marker at the reader's position: its kind, where it sits and
+     *  its content column (padding); null when there is none. */
+    private listMarker;
+    /** A bullet or an ordered marker followed by a space, a tab or the line's end. */
+    private markerAt;
+    private markerKind;
+    /** The columns from the marker to the item's content: 1-4 spaces (or tabs
+     *  to that many columns) after it; with 5 or more, or none (a blank item),
+     *  the content starts one column after the marker. */
+    private paddingAfter;
+    private addChild;
+    private closeUnmatched;
+    /** The next non-space position from where the reader stands, its column,
+     *  and the indent to it. A second call from inside the same run of spaces
+     *  and tabs reuses the first scan (the column a run ends at does not depend
+     *  on where in the run the scan starts), so a line is scanned once however
+     *  many containers it continues. */
+    private findNextNonspace;
+    private advanceNextNonspace;
+    /** Move `count` characters on (or, with `columns`, `count` columns: a tab may be taken in part). */
+    private advanceOffset;
+}

package/dist/interop/copilot-instructions.d.ts

@@ -22,5 +22,6 @@ export declare function renderCopilotInstructions(data: FafData): string;
 /**
  * Write `.github/copilot-instructions.md` — non-destructive (injects/updates the
  * faf block, preserves the rest). Creates the `.github/` directory if absent.
+ * The project folder is the boundary: a `.github` linked outside it is refused.
  */
 export declare function writeCopilotInstructions(dir: string, data: FafData): void;

package/dist/interop/faf.d.ts

@@ -1,24 +1,136 @@
+import { type Document } from 'yaml';
 import type { FafData } from '../core/types.js';
-/** Read and parse a .faf file */
+import { type KeptAlias } from '../core/yaml-edit.js';
+/** Run `call` — a call into faf's scoring kernel with the text of the .faf
+ *  at `path` (or the bytes of the .fafb there) — and turn a rejection by the
+ *  kernel into the one-line refusal. The kernel throws a bare string (or an
+ *  Error) for text it cannot read, some of which yaml reads (a 30-digit
+ *  integer, nesting past the kernel's depth limit); that becomes a
+ *  SafePathError (`not-yaml`): "<file>: faf's scoring kernel could not read
+ *  it (<reason>) — faf left it unchanged". A SafePathError from `call` passes
+ *  through as it is. Every command that hands project.faf (or a .fafb) to
+ *  the kernel calls it through here, after it has read the file as a .faf
+ *  ({@link readFaf}, or {@link readFafFromString} with the path); one that
+ *  edits project.faf (`faf auto`, `faf go`, `faf sync --direction pull`)
+ *  asks the kernel before it writes, so the line is true. `faf diff` and
+ *  `faf log` score a version the kernel cannot read as 0 instead. */
+export declare function withKernel<T>(path: string, call: () => T): T;
+/** Read and parse a .faf file. Always a mapping: an empty file reads as `{}`;
+ *  a file that parses to a scalar or a list throws a SafePathError
+ *  (`not-yaml`, one line) instead of handing callers a value they would
+ *  spread into character keys. A file
+ *  that is not valid YAML throws a SafePathError (`not-yaml`): "<file> is not
+ *  valid YAML (<reason>, line N) — faf left it unchanged". A link that
+ *  leaves the folder, or does not end at a .faf/.fafm file, is refused, and so
+ *  is a file that is not UTF-8. The data remembers the text it was read from:
+ *  writeFaf refuses to write it back over a file that changed since. */
 export declare function readFaf(path: string): FafData;
-/** Write a .faf file from data.
+/** Serialize .faf data to YAML text — the exact bytes writeFaf writes for a
+ *  new file (an existing file is updated in place instead).
  *
  *  If `data._meta.found` is present, it's stripped before serialization and
  *  rendered as a `# found: <list>` YAML comment next to the `type:` field —
  *  Glass Hood doctrine: the user sees WHY the cli classified the project as
- *  it did. `_meta` is a runtime hint, never a serialized .faf field. */
-/** Serialize .faf data to YAML text (the exact bytes writeFaf would write).
- *  Strips runtime `_meta` and renders its `found` rationale as a `# found:`
- *  comment by `type:`. Used by writeFaf and by `faf git --stdout`. */
+ *  it did. `_meta` is a runtime hint, never a serialized .faf field. Used by
+ *  writeFaf and by `faf git --stdout`. */
 export declare function serializeFaf(data: FafData): string;
-export declare function writeFaf(path: string, data: FafData): void;
-/** Read raw YAML text from a .faf file */
+/** What {@link updateFafFile} did. */
+export interface UpdateFafResult {
+    /** True when the file changed on disk; false when the change was a no-op and
+     *  nothing was written. */
+    written: boolean;
+    /** The file's text after the update (its original text when nothing changed). */
+    text: string;
+    /** Aliases the change would have replaced, left as written: `path` is where
+     *  (`stack`), `alias` what the file says there (`*base`). faf never replaces
+     *  or expands an alias; the change at that path is not written. */
+    keptAliases?: KeptAlias[];
+}
+export type { KeptAlias };
+/**
+ * Update an existing .faf in place, keeping every byte the change does not
+ * touch. The file is parsed with yaml's `parseDocument`; `mutate` changes the
+ * Document through its node APIs (`doc.setIn(['stack', 'database'], 'Postgres')`,
+ * `doc.deleteIn([...])`, `doc.getIn([...], true)`); only the text of the nodes
+ * that changed is rewritten. Comments, blank lines, key order, quoting, scalar
+ * source text (`version: 1.10`, `0x1F90`, a 20-digit integer), anchors, unknown
+ * keys (a user's own `_meta` included), CRLF, a BOM and the `%YAML` / `---` /
+ * `...` framing survive — nothing folds at 80 columns. When the change leaves
+ * the data as it was, nothing is written (`written: false`), even if faf's own
+ * layout of the file would differ.
+ *
+ * An alias the change replaces (`doc.set('stack', …)` over `stack: *base`)
+ * is put back: faf never replaces or expands an alias, so that path stays as
+ * written and is listed in `keptAliases`; the rest of the change is written.
+ *
+ * The file must exist. The same link rules as {@link readFaf} (a link must
+ * stay in the folder and end at a .faf/.fafm file) and the atomic write of
+ * `safeWriteFile` apply; the write itself goes only through a link to a file
+ * of the same name. A file that is not valid YAML (SafePathError `not-yaml`,
+ * one line), or not UTF-8, is refused (nothing written); so is a file that
+ * parses to a scalar or a list — the same `not-yaml` refusal readFaf gives,
+ * before `mutate` is called — anything `mutate` throws, and a file that
+ * changed on disk while faf was writing.
+ */
+export declare function updateFafFile(path: string, mutate: (doc: Document) => void): UpdateFafResult;
+/** Options for {@link writeFaf}. */
+export interface WriteFafOptions {
+    /** Write a fresh file from `data` even when one exists — the explicit
+     *  overwrite (`faf init --force`, `faf git --force`). Default: an existing
+     *  file is updated in place with {@link updateFafFile}. */
+    replace?: boolean;
+    /** Called for each alias of an existing file that `data` would change
+     *  (`stack: *base` while `data.stack` has more keys): faf leaves it as
+     *  written — it never replaces or expands an alias — and that path is not
+     *  written. For a fill (data from updateExistingFaf) it is also called for
+     *  each node with an anchor an alias reads that the fill would change
+     *  (`kind: 'anchor'`). `faf auto` prints one line for each. */
+    onAliasKept?: (kept: KeptAlias) => void;
+}
+/** The one line faf prints for an alias (or an anchor an alias reads) it left as written. */
+export declare function aliasKeptNote(kept: KeptAlias): string;
+/** Write a .faf file from data — atomically (temp file, fsync, rename; a
+ *  failure leaves the original as it was), and never through a link that
+ *  leaves the folder or dangles (SafePathError). An in-project link is written
+ *  through and stays a link.
+ *
+ *  An existing file is updated in place ({@link updateFafFile}): `data` is
+ *  compared with what the file holds, and only the values that changed are
+ *  rewritten — so comments, formatting, source text and key order survive, a
+ *  value `data` merely repeats (the text an alias `*g` read as, say) never
+ *  replaces the node the file has, and a write that changes nothing writes
+ *  nothing. A key the file has and `data` leaves out is kept (faf removes
+ *  nothing it did not write). Pass `{ replace: true }` to overwrite the file
+ *  with a fresh render instead. Returns false when nothing was written.
+ *
+ *  An alias in the file (`stack: *base`) is never replaced or expanded: it
+ *  stays as written, and a change `data` makes under it is not written —
+ *  `opts.onAliasKept` hears of each such path. When `data` is a fill (from
+ *  updateExistingFaf), a node with an anchor that an alias reads is left as
+ *  written as well (filling it would change every alias), and reported the
+ *  same way with `kind: 'anchor'`.
+ *
+ *  When `data` came from readFaf of this file (directly, or through
+ *  updateExistingFaf), the write is refused if the file changed on disk since
+ *  that read (SafePathError `changed`: "not written; original kept"), so an
+ *  edit made meanwhile is never written over. A new file is not written over
+ *  one that appeared meanwhile. */
+export declare function writeFaf(path: string, data: FafData, opts?: WriteFafOptions): boolean;
+/** Read raw YAML text from a .faf file (the same link rules as readFaf; a
+ *  file that is not UTF-8 is refused). */
 export declare function readFafRaw(path: string): string;
 /** Parse .faf data from a YAML string — e.g. the output of `git show <ref>:project.faf`.
  *  The readers above are path-only; `faf diff` needs to parse a version that
- *  lives in git history, never on disk. */
-export declare function readFafFromString(text: string): FafData;
-/** Find the .faf file in a directory (walks up) */
+ *  lives in git history, never on disk. With `path` (the file the text was
+ *  read from) the text is read as {@link readFaf} reads a file: text that is
+ *  not valid YAML throws a SafePathError (`not-yaml`) naming it, and so does
+ *  text that parses to a scalar or a list (faf's shape check,
+ *  `asFafMapping`); empty text reads as `{}`. Without `path`, the parsed
+ *  value as it is, or yaml's own error. */
+export declare function readFafFromString(text: string, path?: string): FafData;
+/** Find the .faf file in a directory (walks up one level). The path is
+ *  returned as spelled; a symlinked candidate must pass the readFaf link rules
+ *  or this throws a SafePathError. */
 export declare function findFafFile(dir?: string): string | null;
 /** Repo-root-relative path of a .faf, computed BY git — runtime- and OS-independent.
  *  Replaces `path.relative(top, fafPath)`, which breaks on Windows when git's