MANIFEST.honest

{ NBS Framework Manifest — Single source of truth for tool, skill, and document discovery }
{ Machine-parseable via honest-get, human-readable by design }

type
  EntryKind = (Tool, Skill, Document, Concept);

  Keywords = sequence of String;

  ManifestEntry = record
    kind        : EntryKind;
    name        : String;
    path        : String;
    summary     : String;
    when_to_use : String;
    keywords    : Keywords;
  end;

  Entries = sequence of ManifestEntry;

  Manifest = record
    version : String;
    entries : Entries;
  end;

var manifest : Manifest = (
  version : '0.1.0';
  entries : (

    { ============================================================= }
    { --- Tools --- }
    { ============================================================= }

    (
      kind        : Tool;
      name        : 'nbs-chat';
      path        : 'docs/tools/nbs-chat.md';
      summary     : 'Send, read, search, create, and manage chat files. Includes cursor-set, count, and companion tools nbs-chat-session-end and nbs-chat-resume.';
      when_to_use : 'When you need to send messages, read chat history, search conversations, manage cursors, count messages, or end/resume a session.';
      keywords    : ('chat'; 'send'; 'read'; 'search'; 'message'; 'cursor-set'; 'count'; 'cursor'; 'create'; 'session-end'; 'resume'; 'session'; 'pause');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-terminal';
      path        : 'docs/tools/nbs-chat-terminal.md';
      summary     : 'Interactive terminal client for real-time chat with background message polling and /browse mode.';
      when_to_use : 'When a human wants to participate in a live chat session with agents.';
      keywords    : ('chat'; 'terminal'; 'interactive'; 'browse'; 'live'; 'polling');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-edit';
      path        : 'docs/tools/nbs-chat-edit.md';
      summary     : 'Full-screen editor for chat files with delete, truncate, undo, and atomic rewrite.';
      when_to_use : 'When you need to delete or truncate messages from a chat file.';
      keywords    : ('chat'; 'edit'; 'delete'; 'truncate'; 'undo'; 'editor');
    );

    (
      kind        : Tool;
      name        : 'nbs-dashboard';
      path        : 'docs/tools/tools.md';
      summary     : 'Live full-screen team dashboard showing agent status, sidecar health, cursor position, and activity with drill-down into terminal output.';
      when_to_use : 'When a human wants a continuous at-a-glance view of all agents without repeatedly running /health.';
      keywords    : ('dashboard'; 'monitor'; 'status'; 'agents'; 'sidecars'; 'overview'; 'live');
    );

    (
      kind        : Tool;
      name        : 'nbs-ts';
      path        : 'docs/tools/nbs-ts.md';
      summary     : 'Terminal session manager — create, send input to, read output from, and manage PTY sessions. Supports --idle-timeout=SECS on create for automatic cleanup of abandoned sessions.';
      when_to_use : 'When you need to run commands in a persistent terminal session, capture output, or automate interactive programs.';
      keywords    : ('terminal'; 'session'; 'pty'; 'send'; 'read'; 'capture'; 'interactive'; 'tmux'; 'idle'; 'timeout');
    );

    (
      kind        : Tool;
      name        : 'nbs-md-viewer';
      path        : 'docs/tools/nbs-md-viewer.md';
      summary     : 'Full-screen markdown viewer with syntax highlighting, tables, and vim-style navigation.';
      when_to_use : 'When you need to render and browse a markdown document with styled output in the terminal.';
      keywords    : ('markdown'; 'viewer'; 'render'; 'syntax'; 'highlight'; 'table'; 'pager');
    );

    (
      kind        : Tool;
      name        : 'nbs-bus';
      path        : 'docs/tools/nbs-bus.md';
      summary     : 'Event bus for publishing and consuming events between agents and sidecars.';
      when_to_use : 'When you need to publish events, trigger actions, or coordinate between agents asynchronously.';
      keywords    : ('bus'; 'event'; 'publish'; 'consume'; 'trigger'; 'async'; 'coordination');
    );

    (
      kind        : Tool;
      name        : 'nbs-sidecar';
      path        : 'docs/tools/nbs-sidecar.md';
      summary     : 'Background daemon that monitors agent sessions, detects mentions, and triggers responses.';
      when_to_use : 'Runs automatically alongside each agent — not invoked directly.';
      keywords    : ('sidecar'; 'monitor'; 'mention'; 'detect'; 'trigger'; 'daemon'; 'background');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-init';
      path        : 'docs/tools/nbs-chat-init.md';
      summary     : 'Initialises any directory for NBS team operation by creating the tripod — bus, chat, scribe log — and optionally spawning agents.';
      when_to_use : 'When bootstrapping a new project for multi-agent NBS team work.';
      keywords    : ('init'; 'bootstrap'; 'project'; 'setup'; 'tripod'; 'spawn');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-repair';
      path        : 'docs/tools/nbs-chat-repair.md';
      summary     : 'Detect and repair corrupt lines in nbs-chat files by blanking bad lines and appending salvaged content.';
      when_to_use : 'When a chat file is corrupted or contains garbled lines that break parsing.';
      keywords    : ('chat'; 'repair'; 'corrupt'; 'recovery'; 'salvage'; 'fix');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-remote';
      path        : 'docs/tools/nbs-chat.md';
      summary     : 'SSH proxy for nbs-chat that routes chat commands to a remote host for cross-machine team communication.';
      when_to_use : 'When agents on different machines need to share a chat file via SSH.';
      keywords    : ('chat'; 'remote'; 'ssh'; 'proxy'; 'cross-machine'; 'network');
    );

    (
      kind        : Tool;
      name        : 'nbs-claude';
      path        : 'docs/tools/nbs-claude.md';
      summary     : 'Launches Claude Code inside an nbs-ts session with a background sidecar that monitors for events, messages, and blocking dialogues.';
      when_to_use : 'When spawning a Claude Code agent with integrated sidecar lifecycle management.';
      keywords    : ('claude'; 'launch'; 'sidecar'; 'session'; 'agent'; 'spawn');
    );

    (
      kind        : Tool;
      name        : 'nbs-doctor';
      path        : 'bin/nbs-doctor';
      summary     : 'Diagnose and repair the NBS environment — checks global installation, project structure, symlinks, and binaries.';
      when_to_use : 'When NBS tools are misbehaving or after installation to verify environment health.';
      keywords    : ('diagnose'; 'repair'; 'health'; 'environment'; 'check'; 'fix');
    );

    (
      kind        : Tool;
      name        : 'nbs-hub';
      path        : 'docs/tools/nbs-hub.md';
      summary     : 'Deterministic process enforcement for AI teams — gates spawns, phase transitions, document registry, and decision logging.';
      when_to_use : 'When running multi-agent teams that need spawn gating, phase gates, or shared document tracking.';
      keywords    : ('hub'; 'enforcement'; 'gate'; 'spawn'; 'phase'; 'registry'; 'process');
    );

    (
      kind        : Tool;
      name        : 'nbs-kick-agent';
      path        : 'bin/nbs-kick-agent';
      summary     : 'Level 4 hard restart of a single agent — kills session, cleans PID, resets cursor, respawns, and verifies.';
      when_to_use : 'When an agent is unrecoverably stuck and graduated fixup levels 1-3 have failed.';
      keywords    : ('kick'; 'restart'; 'agent'; 'kill'; 'respawn'; 'recovery');
    );

    (
      kind        : Tool;
      name        : 'nbs-local-run';
      path        : 'docs/tools/nbs-remote.md';
      summary     : 'Run a command locally with the user full login environment — proxy credentials, SSH agent, authenticated remotes.';
      when_to_use : 'When you need proxy access or SSH credentials the sandbox does not have, such as git push.';
      keywords    : ('local'; 'run'; 'credentials'; 'proxy'; 'environment'; 'push'; 'permissions');
    );

    (
      kind        : Tool;
      name        : 'nbs-oracle-reaper';
      path        : 'docs/tools/nbs-oracle-reaper.md';
      summary     : 'Stateless cleanup daemon that kills ephemeral oracle sessions after they post their results to chat.';
      when_to_use : 'Called automatically by the sidecar — not invoked directly by agents.';
      keywords    : ('oracle'; 'reaper'; 'cleanup'; 'ephemeral'; 'kill'; 'stateless');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-build';
      path        : 'bin/nbs-remote-build';
      summary     : 'Run a build command on a remote nbs-ts session while polling for chat messages between checks.';
      when_to_use : 'When building on a remote machine and you need to remain chat-responsive during the build.';
      keywords    : ('remote'; 'build'; 'poll'; 'chat-aware'; 'compile'; 'timeout');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-edit';
      path        : 'docs/tools/nbs-remote.md';
      summary     : 'Edit files on remote machines via scp with a pull-edit-push workflow and diff support.';
      when_to_use : 'When you need to modify a file on a remote machine from within the sandbox.';
      keywords    : ('remote'; 'edit'; 'scp'; 'pull'; 'push'; 'diff');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-git';
      path        : 'docs/tools/nbs-remote-git.md';
      summary     : 'Synchronise git repositories between local and remote machines via SSH using nbs-ts-helper credentials.';
      when_to_use : 'When you need to clone, push, pull, or sync git repos across machines.';
      keywords    : ('remote'; 'git'; 'sync'; 'clone'; 'push'; 'pull'; 'ssh');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-read';
      path        : 'docs/tools/nbs-remote.md';
      summary     : 'Read a file or filtered portion of a file on a remote machine via scp without staging.';
      when_to_use : 'When you need to quickly inspect a remote file without the full pull-edit-push cycle.';
      keywords    : ('remote'; 'read'; 'inspect'; 'scp'; 'head'; 'tail'; 'grep');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-status';
      path        : 'bin/nbs-remote-status';
      summary     : 'Quick state check of a remote nbs-ts session — runs git status, git diff stat, and captures scrollback.';
      when_to_use : 'When you need a fast overview of what is happening on a remote development session.';
      keywords    : ('remote'; 'status'; 'git'; 'scrollback'; 'check'; 'overview');
    );

    (
      kind        : Tool;
      name        : 'nbs-scribe-log';
      path        : 'docs/tools/nbs-scribe-log.md';
      summary     : 'Deterministic CLI for appending structured, timestamped decision entries to the scribe log with validation and bus events.';
      when_to_use : 'When recording a decision, blocker, or risk to the project scribe log.';
      keywords    : ('scribe'; 'log'; 'decision'; 'timestamp'; 'append'; 'structured');
    );

    (
      kind        : Tool;
      name        : 'nbs-scribe-query';
      path        : 'bin/nbs-scribe-query';
      summary     : 'Search the scribe decision log by pattern, ID, handle, tag, or recency, including archived logs.';
      when_to_use : 'When looking up past decisions, searching for context, or counting decision history.';
      keywords    : ('scribe'; 'query'; 'search'; 'decision'; 'history'; 'archive');
    );

    (
      kind        : Tool;
      name        : 'nbs-team-check';
      path        : 'docs/tools/tools.md';
      summary     : 'Report the health status of every agent in a running NBS team — session alive, chat active, context level.';
      when_to_use : 'When diagnosing team health or checking which agents are alive and responsive.';
      keywords    : ('team'; 'health'; 'status'; 'check'; 'agent'; 'alive');
    );

    (
      kind        : Tool;
      name        : 'nbs-ts-grep';
      path        : 'docs/tools/nbs-ts-grep.md';
      summary     : 'Pattern search across one or all agent session logs with ANSI stripping and line-range filtering.';
      when_to_use : 'When searching for specific output, errors, or patterns in agent terminal session logs.';
      keywords    : ('grep'; 'search'; 'session'; 'log'; 'ansi'; 'pattern');
    );

    (
      kind        : Tool;
      name        : 'nbs-ts-helper';
      path        : 'docs/tools/nbs-ts.md';
      summary     : 'Long-running daemon that allocates PTYs with the user login credentials for nbs-ts sessions via Unix socket fd passing.';
      when_to_use : 'Must be running in the user terminal for any nbs-ts, nbs-remote, or nbs-claude operation.';
      keywords    : ('helper'; 'daemon'; 'pty'; 'credentials'; 'socket'; 'fd-passing');
    );

    (
      kind        : Tool;
      name        : 'nbs-ts-query';
      path        : 'docs/tools/nbs-ts-grep.md';
      summary     : 'Extract a range of lines from a single agent session log as clean, ANSI-stripped text.';
      when_to_use : 'When you need to read a specific portion of an agent session log without pattern matching.';
      keywords    : ('query'; 'extract'; 'session'; 'log'; 'lines'; 'range');
    );

    (
      kind        : Tool;
      name        : 'nbs-ts-render';
      path        : 'docs/tools/nbs-ts-render.md';
      summary     : 'Virtual terminal renderer that processes raw PTY output through a headless terminal emulator and outputs plain UTF-8 text.';
      when_to_use : 'When you need to see what a human would see on screen from raw terminal session output.';
      keywords    : ('render'; 'terminal'; 'vt100'; 'ansi'; 'screen'; 'emulator');
    );

    (
      kind        : Tool;
      name        : 'nbs-ts-sysctl';
      path        : 'docs/tools/nbs-ts-sysctl.md';
      summary     : 'Manages the nbs-ts-helper daemon as a systemd user service — install, start, stop, diagnostics, and removal.';
      when_to_use : 'When setting up or managing the nbs-ts-helper systemd service for persistent PTY allocation.';
      keywords    : ('sysctl'; 'systemd'; 'service'; 'install'; 'daemon'; 'lifecycle');
    );

    (
      kind        : Tool;
      name        : 'nbs-workers';
      path        : 'docs/tools/nbs-workers.md';
      summary     : 'Higher-level worker lifecycle management with unique naming, persistent logging, and task file integration.';
      when_to_use : 'When a supervisor needs to spawn, monitor, search, or kill Claude worker instances.';
      keywords    : ('workers'; 'spawn'; 'lifecycle'; 'logging'; 'task'; 'supervisor');
    );

    (
      kind        : Tool;
      name        : 'honest-get';
      path        : 'lib/honest/docs/cli-reference.md';
      summary     : 'Extract field values from an Honest document by variable name and field path.';
      when_to_use : 'When you need to programmatically read specific fields from an Honest file.';
      keywords    : ('honest'; 'get'; 'extract'; 'field'; 'value'; 'query');
    );

    (
      kind        : Tool;
      name        : 'honest-parse';
      path        : 'lib/honest/docs/cli-reference.md';
      summary     : 'Parse and validate an Honest document, reporting diagnostics for any syntax or structure errors.';
      when_to_use : 'When validating that an Honest file is syntactically correct before use.';
      keywords    : ('honest'; 'parse'; 'validate'; 'syntax'; 'check'; 'diagnostic');
    );

    (
      kind        : Tool;
      name        : 'honest-fmt';
      path        : 'lib/honest/docs/cli-reference.md';
      summary     : 'Reformat an Honest document into wire mode or human-readable document mode.';
      when_to_use : 'When you need to normalise or pretty-print an Honest file.';
      keywords    : ('honest'; 'format'; 'wire'; 'document'; 'pretty-print'; 'normalise');
    );

    (
      kind        : Tool;
      name        : 'honest-build';
      path        : 'lib/honest/docs/cli-reference.md';
      summary     : 'Construct an Honest document from CLI key=value arguments with support for nested records and sequences.';
      when_to_use : 'When programmatically generating Honest documents from shell scripts or automation.';
      keywords    : ('honest'; 'build'; 'construct'; 'generate'; 'cli'; 'key-value');
    );

    (
      kind        : Tool;
      name        : 'honest-extract';
      path        : 'lib/honest/docs/cli-reference.md';
      summary     : 'Extract the first valid Honest document embedded in mixed text such as markdown or chat logs.';
      when_to_use : 'When an Honest document is embedded in a larger file and needs to be isolated for parsing.';
      keywords    : ('honest'; 'extract'; 'embedded'; 'mixed-text'; 'scan'; 'isolate');
    );

    (
      kind        : Tool;
      name        : 'nbs-claude-build-args';
      path        : 'bin/nbs-claude-build-args';
      summary     : 'Build the Claude CLI argument array from environment and caller flags, consuming nbs-specific options and passing the rest through.';
      when_to_use : 'Called internally by nbs-claude — not invoked directly by agents.';
      keywords    : ('claude'; 'args'; 'model'; 'session'; 'passthrough'; 'build');
    );

    (
      kind        : Tool;
      name        : 'nbs-claude-remote';
      path        : 'bin/nbs-claude-remote';
      summary     : 'Launch Claude Code on a remote machine via SSH, creating a tmux session and attaching the local terminal.';
      when_to_use : 'When you need to run a Claude Code agent on a remote machine where the project and .nbs/ directory live.';
      keywords    : ('claude'; 'remote'; 'ssh'; 'tmux'; 'launch'; 'attach');
    );

    (
      kind        : Tool;
      name        : 'nbs-digest-spawn';
      path        : 'bin/nbs-digest-spawn';
      summary     : 'Spawn an ephemeral worker to produce a structured digest of a chat file and post the summary to chat.';
      when_to_use : 'When recovering agents after downtime and they need a briefing on what happened in the chat.';
      keywords    : ('digest'; 'chat'; 'summary'; 'spawn'; 'worker'; 'restart'; 'briefing');
    );

    (
      kind        : Tool;
      name        : 'nbs-launch-agent';
      path        : 'bin/nbs-launch-agent';
      summary     : 'Shared bash function that launches a single nbs-claude agent via setsid with correct environment scrubbing.';
      when_to_use : 'When spawning agents — source this file and call launch_agent instead of invoking nbs-claude directly.';
      keywords    : ('launch'; 'agent'; 'spawn'; 'setsid'; 'function'; 'source');
    );

    (
      kind        : Tool;
      name        : 'nbs-local-session';
      path        : 'bin/nbs-local-session';
      summary     : 'Create a persistent local shell session via nbs-ts-helper with the user full login environment. Self-terminates after 1 hour of inactivity (configurable via NBS_SESSION_IDLE_TIMEOUT).';
      when_to_use : 'When you need a local shell with full credentials for build commands, git operations, or proxy access.';
      keywords    : ('local'; 'session'; 'shell'; 'login'; 'credentials'; 'persistent'; 'idle'; 'timeout');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-diff';
      path        : 'bin/nbs-remote-diff';
      summary     : 'Pull git diff output from a remote nbs-ts session with optional chat posting and diffstat mode.';
      when_to_use : 'When you need to see git changes on a remote machine without a full interactive session.';
      keywords    : ('remote'; 'diff'; 'git'; 'stat'; 'staged'; 'chat'; 'post');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-run';
      path        : 'bin/nbs-remote-run';
      summary     : 'Run a single command on a remote machine via an ephemeral SSH nbs-ts session and return the captured output.';
      when_to_use : 'When you need to run one command on a remote host without managing a persistent session.';
      keywords    : ('remote'; 'run'; 'ssh'; 'ephemeral'; 'command'; 'capture');
    );

    (
      kind        : Tool;
      name        : 'nbs-remote-session';
      path        : 'bin/nbs-remote-session';
      summary     : 'Create a persistent SSH shell session on a remote machine and return a handle for use with nbs-ts commands. Self-terminates after 1 hour of inactivity (configurable via NBS_SESSION_IDLE_TIMEOUT).';
      when_to_use : 'When you need a long-lived remote shell for multiple commands, builds, or interactive work.';
      keywords    : ('remote'; 'session'; 'ssh'; 'persistent'; 'handle'; 'shell'; 'idle'; 'timeout');
    );

    (
      kind        : Tool;
      name        : 'nbs-ssh-bridge';
      path        : 'docs/tools/nbs-ssh-bridge.md';
      summary     : 'Drop-in ssh/scp replacement that configures and reuses ControlMaster connections — first connection authenticates, subsequent connections piggyback without re-authentication.';
      when_to_use : 'When making multiple SSH or SCP connections to the same host and want to avoid repeated authentication handshakes.';
      keywords    : ('ssh'; 'scp'; 'remote'; 'multiplexing'; 'ControlMaster'; 'connection'; 'authentication'; 'bridge');
    );

    (
      kind        : Tool;
      name        : 'nbs-sidecar-find-session';
      path        : 'bin/nbs-sidecar-find-session';
      summary     : 'Find an alive nbs-ts session by exact name — used by sidecar-loops for project-scoped session re-discovery after agent restarts.';
      when_to_use : 'Called by sidecar-loop scripts — not invoked directly by agents.';
      keywords    : ('sidecar'; 'session'; 'find'; 'rediscovery'; 'restart'; 'loop');
    );

    (
      kind        : Tool;
      name        : 'nbs-scp-bridge';
      path        : 'docs/tools/nbs-ssh-bridge.md';
      summary     : 'SCP with connection multiplexing — symlink to nbs-ssh-bridge, detects invocation name and routes to scp.';
      when_to_use : 'When transferring files via SCP and want to reuse an existing SSH master connection.';
      keywords    : ('scp'; 'ssh'; 'remote'; 'transfer'; 'multiplexing'; 'bridge');
    );

    (
      kind        : Tool;
      name        : 'nbs-file-browser';
      path        : 'src/nbs-file-browser/main.c';
      summary     : 'Full-screen TUI file browser with multi-column layout, syntax-highlighted viewing via bat, and markdown rendering via nbs-md-viewer.';
      when_to_use : 'When browsing project files from the terminal or via /file in nbs-chat-terminal.';
      keywords    : ('file'; 'browser'; 'navigate'; 'directory'; 'bat'; 'syntax'; 'highlight'; 'TUI');
    );

    (
      kind        : Tool;
      name        : 'nbs-sidecar-restart';
      path        : 'bin/nbs-sidecar-restart';
      summary     : 'Hot-restart running sidecars to pick up new binaries, or respawn missing sidecars for active agent sessions. Kills sidecar-loops before sidecars to prevent respawn races.';
      when_to_use : 'After rebuilding the sidecar binary, or when agents are deaf because their sidecar process died.';
      keywords    : ('sidecar'; 'restart'; 'respawn'; 'hot-restart'; 'binary'; 'upgrade'; 'dedup');
    );

    (
      kind        : Tool;
      name        : 'nbs-team-status';
      path        : 'docs/tools/nbs-team-status.md';
      summary     : 'Show every team process (sessions, sidecars, sidecar-loops) with duplicate and orphan detection.';
      when_to_use : 'When diagnosing duplicate sidecars, orphan processes, or verifying clean process state after restart.';
      keywords    : ('team'; 'status'; 'process'; 'duplicate'; 'orphan'; 'sidecar'; 'diagnosis');
    );

    (
      kind        : Tool;
      name        : 'nbs-team-kill';
      path        : 'docs/tools/nbs-team-kill.md';
      summary     : 'Clean-slate kill of all team processes — sessions, sidecars, and sidecar-loops for a given tag.';
      when_to_use : 'When you need to kill all team processes before a full restart, or to clear process leaks.';
      keywords    : ('team'; 'kill'; 'clean'; 'process'; 'restart'; 'leak'; 'slate');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-session-end';
      path        : 'bin/nbs-chat-session-end';
      summary     : 'Graceful team shutdown with countdown timer — posts session-end message, waits, then creates control-pause to suppress notifications and ephemeral triggers.';
      when_to_use : 'When the supervisor has confirmed the terminal goal is complete and wants to pause the team gracefully. Cancellable during countdown via nbs-chat-resume.';
      keywords    : ('session-end'; 'pause'; 'shutdown'; 'countdown'; 'stasis'; 'idle'; 'graceful');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-resume';
      path        : 'bin/nbs-chat-resume';
      summary     : 'Cancel session-end countdown or resume from pause — deletes control-pause file and kills any active countdown timer.';
      when_to_use : 'When resuming a paused team or cancelling a session-end countdown before it completes.';
      keywords    : ('resume'; 'unpause'; 'cancel'; 'session-end'; 'restart'; 'wake');
    );

    (
      kind        : Tool;
      name        : 'nbs-spawn-worker';
      path        : 'bin/nbs-spawn-worker';
      summary     : 'Spawn an ephemeral worker agent with a task file, skill content, and background monitor that kills the session on completion.';
      when_to_use : 'When nbs-workers needs to launch an ephemeral Claude instance for a specific task with lifecycle management.';
      keywords    : ('spawn'; 'worker'; 'ephemeral'; 'task'; 'monitor'; 'lifecycle');
    );

    (
      kind        : Tool;
      name        : 'nbs-help (CLI)';
      path        : 'bin/nbs-help';
      summary     : 'Search the MANIFEST.honest by keyword, kind, or list all entries — the CLI counterpart to the nbs-help skill.';
      when_to_use : 'When you need to find a tool, skill, or document by keyword from the command line.';
      keywords    : ('help'; 'search'; 'manifest'; 'lookup'; 'keyword'; 'list');
    );

    (
      kind        : Tool;
      name        : 'nbs-chat-terminal-restart.sh';
      path        : 'bin/nbs-chat-terminal-restart.sh';
      summary     : 'Auto-restart the NBS agent team via Level 4 cold restart when the terminal watchdog detects fewer than 3 agent sessions alive.';
      when_to_use : 'Called automatically by the terminal watchdog — not invoked directly by agents.';
      keywords    : ('restart'; 'watchdog'; 'cold-restart'; 'terminal'; 'auto-restart'; 'team');
    );

    { ============================================================= }
    { --- Skills --- }
    { ============================================================= }

    (
      kind        : Skill;
      name        : 'nbs-testkeeper';
      path        : 'claude_tools/nbs-testkeeper.md';
      summary     : 'Test suite ownership — run tests, report results with evidence, challenge unverified claims.';
      when_to_use : 'Loaded automatically for the testkeeper agent role.';
      keywords    : ('test'; 'testing'; 'verification'; 'benchmark'; 'coverage'; 'ABBA'; 'falsification');
    );

    (
      kind        : Skill;
      name        : 'nbs-theologian';
      path        : 'claude_tools/nbs-theologian.md';
      summary     : 'Architecture advisor — read code, map invariants, identify risks, review fixes.';
      when_to_use : 'Loaded automatically for the theologian agent role.';
      keywords    : ('architecture'; 'review'; 'invariant'; 'risk'; 'design'; 'theory');
    );

    (
      kind        : Skill;
      name        : 'nbs-supervisor';
      path        : 'claude_tools/nbs-supervisor.md';
      summary     : 'Team coordination — delegate work, track progress, manage agent lifecycle.';
      when_to_use : 'Loaded automatically for the supervisor agent role.';
      keywords    : ('supervisor'; 'coordinate'; 'delegate'; 'team'; 'manage'; 'lifecycle');
    );

    (
      kind        : Skill;
      name        : 'nbs-discovery';
      path        : 'claude_tools/nbs-discovery.md';
      summary     : 'Collaborative, read-only discovery of artefacts in projects lacking epistemic structure.';
      when_to_use : 'When onboarding to a disordered project to understand its state before making changes.';
      keywords    : ('discovery'; 'read-only'; 'artefact'; 'epistemic'; 'onboarding'; 'report');
    );

    (
      kind        : Skill;
      name        : 'nbs-recovery';
      path        : 'claude_tools/nbs-recovery.md';
      summary     : 'Step-wise restructuring and consolidation of projects based on a prior discovery report.';
      when_to_use : 'After running nbs-discovery, when ready to restructure and establish epistemic discipline.';
      keywords    : ('recovery'; 'restructure'; 'consolidate'; 'discipline'; 'action'; 'fix');
    );

    (
      kind        : Skill;
      name        : 'nbs-investigation';
      path        : 'claude_tools/nbs-investigation.md';
      summary     : 'Falsification-driven exploration of a specific hypothesis as an isolated side quest.';
      when_to_use : 'When you have a specific hypothesis to test that is separate from main development work.';
      keywords    : ('investigation'; 'hypothesis'; 'falsification'; 'side-quest'; 'test'; 'explore');
    );

    (
      kind        : Skill;
      name        : 'nbs-review';
      path        : 'claude_tools/nbs.md';
      summary     : 'Systematic audit of reasoning quality, goal alignment, and falsification discipline across a project.';
      when_to_use : 'When reviewing work for epistemic rigour — checks for investigations, terminal weathering, and drift.';
      keywords    : ('review'; 'audit'; 'reasoning'; 'alignment'; 'quality'; 'drift');
    );

    (
      kind        : Skill;
      name        : 'nbs-discovery-verify';
      path        : 'claude_tools/nbs-discovery-verify.md';
      summary     : 'Checkpoint verification that a discovery report is complete before proceeding to recovery.';
      when_to_use : 'Immediately after completing nbs-discovery to verify the report captures everything discussed.';
      keywords    : ('discovery'; 'verify'; 'checkpoint'; 'completeness'; 'report'; 'check');
    );

    (
      kind        : Skill;
      name        : 'nbs-doc-plan';
      path        : 'claude_tools/nbs-doc-plan.md';
      summary     : 'Interactive planning for documents — clarify goals, audience, and structure before writing a single word.';
      when_to_use : 'Before writing any significant document to prevent conception-phase failures.';
      keywords    : ('document'; 'plan'; 'audience'; 'structure'; 'goals'; 'conception');
    );

    (
      kind        : Skill;
      name        : 'nbs-doc-describe';
      path        : 'claude_tools/nbs-doc-describe.md';
      summary     : 'Interactive help describing systems, code, or concepts — find the right words through questioning.';
      when_to_use : 'When you know what something is but need help articulating it clearly for a reader.';
      keywords    : ('describe'; 'document'; 'explain'; 'articulate'; 'system'; 'concept');
    );

    (
      kind        : Skill;
      name        : 'nbs-doc-analyse';
      path        : 'claude_tools/nbs-doc-analyse.md';
      summary     : 'Falsification-focused analysis of documents for hidden goals, rhetoric, and bullshit.';
      when_to_use : 'When you need to expose the gap between stated goals and actual goals in a document or communication.';
      keywords    : ('analyse'; 'document'; 'rhetoric'; 'bullshit'; 'goals'; 'falsification');
    );

    (
      kind        : Skill;
      name        : 'nbs-doc-help';
      path        : 'claude_tools/nbs-doc-help.md';
      summary     : 'Interactive mentor-style guidance for the NBS document tools.';
      when_to_use : 'When you need help choosing or using the nbs-doc-plan, nbs-doc-describe, or nbs-doc-analyse tools.';
      keywords    : ('document'; 'help'; 'guidance'; 'mentor'; 'tools'; 'interactive');
    );

    (
      kind        : Skill;
      name        : 'nbs-natural';
      path        : 'claude_tools/nbs-natural.md';
      summary     : 'Exit Precise Technical English mode and return to natural language communication.';
      when_to_use : 'When PTE constraints are no longer needed and you want informal communication.';
      keywords    : ('natural'; 'language'; 'pte'; 'exit'; 'informal'; 'mode');
    );

    (
      kind        : Skill;
      name        : 'nbs-oracular-speech';
      path        : 'claude_tools/nbs-oracular-speech.md';
      summary     : 'Compressed insight mode using productive ambiguity and metaphor to force interpretation.';
      when_to_use : 'When standard prose is too diffuse and you need dense, aphoristic expression.';
      keywords    : ('oracular'; 'speech'; 'metaphor'; 'compressed'; 'insight'; 'ambiguity');
    );

    (
      kind        : Skill;
      name        : 'nbs-bus (skill)';
      path        : 'claude_tools/nbs-bus.md';
      summary     : 'Event-driven coordination skill — publish events, check queues, and manage the bus from an agent context.';
      when_to_use : 'When an agent needs to publish events, check pending work, or manage bus state.';
      keywords    : ('bus'; 'event'; 'publish'; 'queue'; 'coordination'; 'agent');
    );

    (
      kind        : Skill;
      name        : 'nbs-chat-digest';
      path        : 'claude_tools/nbs-chat-digest.md';
      summary     : 'Ephemeral agent that extracts structured learnings from chat files into persistent knowledge.';
      when_to_use : 'When chat history needs to be distilled into structured, reusable learnings.';
      keywords    : ('chat'; 'digest'; 'learnings'; 'extract'; 'ephemeral'; 'knowledge');
    );

    (
      kind        : Skill;
      name        : 'nbs-teams-start';
      path        : 'claude_tools/nbs-teams-start.md';
      summary     : 'Cold start bootstrap — gather user intent, run nbs-chat-init, spawn and verify a full multi-agent team.';
      when_to_use : 'When bootstrapping a new NBS team from scratch in a project with no existing .nbs/ structure.';
      keywords    : ('teams'; 'start'; 'bootstrap'; 'cold-start'; 'spawn'; 'init');
    );

    (
      kind        : Skill;
      name        : 'nbs-hub (skill)';
      path        : 'claude_tools/nbs-hub.md';
      summary     : 'Deterministic process enforcement skill — spawn gating, phase transitions, and decision logging for supervisors.';
      when_to_use : 'When a supervisor needs to interact with the hub for teams work, spawn gating, or phase management.';
      keywords    : ('hub'; 'enforcement'; 'gate'; 'spawn'; 'phase'; 'supervisor');
    );

    (
      kind        : Skill;
      name        : 'nbs-init';
      path        : 'claude_tools/nbs-init.md';
      summary     : 'Configure a project CLAUDE.md to reference NBS engineering standards — idempotent and safe to repeat.';
      when_to_use : 'When setting up a project to use NBS engineering standards for the first time.';
      keywords    : ('init'; 'configure'; 'CLAUDE.md'; 'standards'; 'project'; 'setup');
    );

    (
      kind        : Skill;
      name        : 'nbs-help';
      path        : 'claude_tools/nbs-help.md';
      summary     : 'Interactive mentor-style guidance for the NBS framework — ask, explain, check understanding.';
      when_to_use : 'When you need help understanding any part of the NBS framework.';
      keywords    : ('help'; 'guidance'; 'mentor'; 'framework'; 'interactive'; 'explain');
    );

    (
      kind        : Skill;
      name        : 'nbs-poll';
      path        : 'claude_tools/nbs-poll.md';
      summary     : 'Check for pending bus events and unread chat messages — currently disabled but retained for reference.';
      when_to_use : 'Currently disabled (NBS_POLL_INTERVAL=0) — sidecar notifications replaced polling.';
      keywords    : ('poll'; 'check'; 'messages'; 'events'; 'bus'; 'disabled');
    );

    (
      kind        : Skill;
      name        : 'nbs-teams-restart';
      path        : 'claude_tools/nbs-teams-restart.md';
      summary     : 'Partial recovery after downtime — triage all agents, assess before acting, recover in priority order.';
      when_to_use : 'After overnight idle, crash, or network partition to recover a multi-agent team.';
      keywords    : ('teams'; 'restart'; 'recovery'; 'triage'; 'downtime'; 'partial');
    );

    (
      kind        : Skill;
      name        : 'nbs-remote-dev';
      path        : 'claude_tools/nbs-remote-dev.md';
      summary     : 'Remote development workflow patterns for editing, building, and debugging on remote machines from an AI agent.';
      when_to_use : 'When doing sustained development work on a remote machine through nbs-ts sessions.';
      keywords    : ('remote'; 'development'; 'workflow'; 'build'; 'debug'; 'ssh');
    );

    (
      kind        : Skill;
      name        : 'nbs-gdb';
      path        : 'claude_tools/nbs-gdb.md';
      summary     : 'Falsification-focused GDB debugging via nbs-ts — hypothesis before commands, measurement not exploration.';
      when_to_use : 'When debugging C/C++ programs and you need persistent GDB sessions with hypothesis discipline.';
      keywords    : ('gdb'; 'debug'; 'hypothesis'; 'falsification'; 'breakpoint'; 'persistent');
    );

    (
      kind        : Skill;
      name        : 'nbs-terminal-weathering';
      path        : 'claude_tools/nbs-terminal-weathering.md';
      summary     : 'Hypothesis-driven performance optimisation of Python systems through evidence-gated architectural intervention.';
      when_to_use : 'When conducting performance optimisation work that requires profiling, benchmarking, and C extension writing.';
      keywords    : ('performance'; 'optimisation'; 'profiling'; 'benchmark'; 'c-extension'; 'hypothesis');
    );

    (
      kind        : Skill;
      name        : 'nbs-terminal-weathering-review';
      path        : 'claude_tools/nbs-terminal-weathering-review.md';
      summary     : 'Correctness review for terminal weathering sessions — applied in addition to the normal NBS review.';
      when_to_use : 'When reviewing a branch or session that contains terminal weathering performance work.';
      keywords    : ('review'; 'weathering'; 'correctness'; 'performance'; 'check'; 'supplementary');
    );

    (
      kind        : Skill;
      name        : 'nbs-teams-fixup';
      path        : 'claude_tools/nbs-teams-fixup.md';
      summary     : 'Diagnose and restart stalled agents using a graduated escalation ladder from least to most destructive.';
      when_to_use : 'When an agent is stalled and needs graduated recovery — context compaction check before hard restart.';
      keywords    : ('fixup'; 'stalled'; 'escalation'; 'restart'; 'diagnose'; 'recovery');
    );

    (
      kind        : Skill;
      name        : 'nbs-notify';
      path        : 'claude_tools/nbs-notify.md';
      summary     : 'Process pending events or messages injected by the sidecar notification system.';
      when_to_use : 'Triggered automatically by sidecar when bus events or unread chat messages are detected.';
      keywords    : ('notify'; 'sidecar'; 'event'; 'message'; 'pending'; 'trigger');
    );

    (
      kind        : Skill;
      name        : 'nbs-audit';
      path        : 'claude_tools/nbs-audit.md';
      summary     : 'Full codebase audit against engineering standards with parallel sub-agents and adversarial TDD fix plans.';
      when_to_use : 'When auditing an entire codebase for engineering standards violations and producing a fix plan.';
      keywords    : ('audit'; 'standards'; 'violations'; 'TDD'; 'parallel'; 'codebase');
    );

    (
      kind        : Skill;
      name        : 'nbs-scribe';
      path        : 'claude_tools/nbs-scribe.md';
      summary     : 'Institutional memory agent — observes conversations and distils decisions into a structured log that survives restarts.';
      when_to_use : 'Loaded automatically for the scribe agent role in a multi-agent team.';
      keywords    : ('scribe'; 'memory'; 'decision'; 'log'; 'institutional'; 'distil');
    );

    (
      kind        : Skill;
      name        : 'nbs-medic';
      path        : 'claude_tools/nbs-medic.md';
      summary     : 'Meta-cognitive monitor that detects hallucinations, motivated reasoning, and epistemic decay — communicates only via warnings.';
      when_to_use : 'Loaded automatically for the medic agent role — monitors reasoning quality silently.';
      keywords    : ('medic'; 'monitor'; 'hallucination'; 'reasoning'; 'epistemic'; 'warning');
    );

    (
      kind        : Skill;
      name        : 'nbs-gatekeeper';
      path        : 'claude_tools/nbs-gatekeeper.md';
      summary     : 'Pre-push commit review agent — reviews commits for correctness, consistency, and completeness before code reaches the remote.';
      when_to_use : 'Loaded automatically for the gatekeeper agent role before any git push.';
      keywords    : ('gatekeeper'; 'review'; 'commit'; 'push'; 'correctness'; 'pre-push');
    );

    (
      kind        : Skill;
      name        : 'nbs-worker';
      path        : 'claude_tools/nbs-worker.md';
      summary     : 'Task execution role — execute a specific task with fresh context, report findings, and exit.';
      when_to_use : 'Loaded automatically for worker agents spawned by a supervisor in a teams hierarchy.';
      keywords    : ('worker'; 'task'; 'execute'; 'report'; 'fresh-context'; 'role');
    );

    (
      kind        : Skill;
      name        : 'nbs-pythia';
      path        : 'claude_tools/nbs-pythia.md';
      summary     : 'Ephemeral oracle that reads the decision log, assesses trajectory and risk, posts a structured checkpoint, and exits.';
      when_to_use : 'Spawned automatically at checkpoints to provide trajectory and risk assessment.';
      keywords    : ('pythia'; 'oracle'; 'trajectory'; 'risk'; 'checkpoint'; 'ephemeral');
    );

    (
      kind        : Skill;
      name        : 'nbs-librarian';
      path        : 'claude_tools/nbs-librarian.md';
      summary     : 'Ephemeral helper oracle that knows where the answers are, what tools exist, and what the team decided before.';
      when_to_use : 'Spawned when agents are stuck or drifting from prior decisions and need institutional knowledge.';
      keywords    : ('librarian'; 'oracle'; 'knowledge'; 'helper'; 'decisions'; 'unstick');
    );

    (
      kind        : Skill;
      name        : 'nbs-pte';
      path        : 'claude_tools/nbs-pte.md';
      summary     : 'Activate Precise Technical English mode — constrained prose with RFC 2119 modals and Honest type definitions.';
      when_to_use : 'When specifications require unambiguous language with explicit cardinality and condition-action structure.';
      keywords    : ('pte'; 'precise'; 'technical'; 'english'; 'unambiguous'; 'specification');
    );

    (
      kind        : Skill;
      name        : 'nbs-teams-help';
      path        : 'claude_tools/nbs-teams-help.md';
      summary     : 'Interactive mentor-style guidance for NBS teams usage and operations.';
      when_to_use : 'When you need help understanding how to use NBS teams features.';
      keywords    : ('teams'; 'help'; 'guidance'; 'mentor'; 'interactive'; 'operations');
    );

    (
      kind        : Skill;
      name        : 'nbs-shepard';
      path        : 'claude_tools/nbs-shepard.md';
      summary     : 'Ephemeral team shepherd oracle that assesses team dynamics and posts actionable coordination recommendations.';
      when_to_use : 'Spawned at checkpoints to evaluate how well the team is coordinating and suggest improvements.';
      keywords    : ('shepard'; 'oracle'; 'team'; 'dynamics'; 'coordination'; 'assessment');
    );

    (
      kind        : Skill;
      name        : 'nbs-fixup-auto';
      path        : 'claude_tools/nbs-fixup-auto.md';
      summary     : 'Ephemeral self-repair agent that diagnoses all seven permanent team agents, escalates through graduated levels, and posts a health summary.';
      when_to_use : 'Triggered automatically by the sidecar to check and repair the team — not invoked manually.';
      keywords    : ('fixup'; 'self-repair'; 'health'; 'escalation'; 'restart'; 'diagnose'; 'ephemeral');
    );

    (
      kind        : Skill;
      name        : 'nbs-manifest-audit';
      path        : 'claude_tools/nbs-manifest-audit.md';
      summary     : 'Audit MANIFEST.honest against the filesystem for stale paths, missing entries, and summary quality issues.';
      when_to_use : 'When maintaining the manifest to find missing tools, dead paths, or vague summaries.';
      keywords    : ('manifest'; 'audit'; 'stale'; 'missing'; 'quality'; 'honest'; 'validate');
    );

    (
      kind        : Skill;
      name        : 'nbs-teams-chat';
      path        : 'claude_tools/nbs-teams-chat.md';
      summary     : 'AI-to-AI chat protocol — how agents send, read, search, and receive notifications via nbs-chat in a multi-agent team.';
      when_to_use : 'Loaded for every agent in a multi-agent team to establish chat communication patterns and rules.';
      keywords    : ('chat'; 'teams'; 'protocol'; 'notification'; 'mention'; 'send'; 'read');
    );

    (
      kind        : Skill;
      name        : 'nbs-cursor-diagnosis';
      path        : 'claude_tools/nbs-cursor-diagnosis.md';
      summary     : 'Diagnose and repair pathological cursor desync — check cursor state, sidecar health, and notification delivery path.';
      when_to_use : 'When an agent stops receiving notifications, processes old messages, or the sidecar appears stuck.';
      keywords    : ('cursor'; 'desync'; 'diagnosis'; 'repair'; 'notification'; 'sidecar'; 'unread');
    );

    { ============================================================= }
    { --- Documents and Concepts --- }
    { ============================================================= }

    (
      kind        : Document;
      name        : 'C++ to C Patterns';
      path        : 'terminal-weathering/concepts/cpp-to-c-patterns.md';
      summary     : '19 conversion patterns for porting C++ code to pure C with risk levels and pitfalls.';
      when_to_use : 'When converting C++ files to C — read before starting any conversion.';
      keywords    : ('c++'; 'c'; 'porting'; 'conversion'; 'template'; 'RAII'; 'enum class'; 'namespace');
    );

    (
      kind        : Document;
      name        : 'Terminal Weathering';
      path        : 'terminal-weathering/concepts/terminal-weathering.md';
      summary     : 'Hypothesis-driven performance optimisation methodology with evidence-gated architectural intervention.';
      when_to_use : 'When planning or executing performance optimisation work on a codebase.';
      keywords    : ('performance'; 'optimisation'; 'hypothesis'; 'profiling'; 'benchmark'; 'architecture');
    );

    (
      kind        : Concept;
      name        : 'Goals';
      path        : 'concepts/goals.md';
      summary     : 'Terminal vs instrumental goals — the root distinction that prevents optimising the wrong thing.';
      when_to_use : 'When setting project direction or when instrumental goals risk consuming all resources.';
      keywords    : ('goals'; 'terminal'; 'instrumental'; 'strategic'; 'tactical'; 'alignment');
    );

    (
      kind        : Concept;
      name        : 'Falsifiability';
      path        : 'concepts/falsifiability.md';
      summary     : 'The epistemological foundation — any claim worth making must articulate what would prove it wrong.';
      when_to_use : 'When evaluating claims, writing tests, or challenging assertions that lack falsification criteria.';
      keywords    : ('falsifiability'; 'epistemology'; 'counterexample'; 'claim'; 'verification'; 'proof');
    );

    (
      kind        : Concept;
      name        : 'Rhetoric';
      path        : 'concepts/rhetoric.md';
      summary     : 'Ethos, Pathos, Logos in engineering — exposing the hidden emotional motivations behind logical arguments.';
      when_to_use : 'When analysing why a technical decision is being pushed or when aesthetic preferences masquerade as logic.';
      keywords    : ('rhetoric'; 'ethos'; 'pathos'; 'logos'; 'persuasion'; 'motivation');
    );

    (
      kind        : Concept;
      name        : 'Bullshit Detection';
      path        : 'concepts/bullshit-detection.md';
      summary     : 'Identifying indifference to truth — the gap between sounding right and being right, especially in AI output.';
      when_to_use : 'When evaluating AI output or human claims that optimise for plausibility over accuracy.';
      keywords    : ('bullshit'; 'detection'; 'truth'; 'plausibility'; 'RLHF'; 'indifference');
    );

    (
      kind        : Concept;
      name        : 'Engineering Standards';
      path        : 'concepts/engineering-standards.md';
      summary     : 'Verification-first engineering — safety from verbs not nouns, falsifiability as foundation, test the real system.';
      when_to_use : 'When writing code, reviewing code, or auditing a codebase against NBS quality standards.';
      keywords    : ('standards'; 'verification'; 'assertions'; 'testing'; 'invariants'; 'quality');
    );

    (
      kind        : Concept;
      name        : 'Coordination';
      path        : 'concepts/coordination.md';
      summary     : 'How isolated AI agents coordinate via files, bus events, and sidecars without the ability to interrupt each other.';
      when_to_use : 'When designing multi-agent workflows or debugging coordination failures between agents.';
      keywords    : ('coordination'; 'agents'; 'polling'; 'sidecar'; 'bus'; 'file-authority');
    );

    (
      kind        : Concept;
      name        : 'Precise Technical English';
      path        : 'concepts/pte.md';
      summary     : 'Constrained subset of English that eliminates ambiguity through RFC 2119 modals, explicit cardinality, and Honest types.';
      when_to_use : 'When writing specifications that must be unambiguous — read before using PTE mode.';
      keywords    : ('pte'; 'precision'; 'ambiguity'; 'specification'; 'modals'; 'honest');
    );

    (
      kind        : Document;
      name        : 'What NBS Is';
      path        : 'docs/getting-started/01-what-nbs-is.md';
      summary     : 'The problem NBS solves — epistemic failure in AI collaboration, goal drift, confirmation bias, and authority worship.';
      when_to_use : 'When onboarding someone who needs to understand why NBS exists and what problems it addresses.';
      keywords    : ('introduction'; 'overview'; 'problem'; 'drift'; 'bias'; 'epistemic');
    );

    (
      kind        : Document;
      name        : 'Setup Guide';
      path        : 'docs/getting-started/02-setup.md';
      summary     : 'Installation prerequisites and step-by-step setup for a working NBS environment.';
      when_to_use : 'When installing NBS for the first time or verifying installation prerequisites.';
      keywords    : ('setup'; 'install'; 'prerequisites'; 'gcc'; 'make'; 'getting-started');
    );

    (
      kind        : Document;
      name        : 'Tools Reference';
      path        : 'docs/tools/tools.md';
      summary     : 'Master reference for every tool in ~/.nbs/bin/ with purpose, usage, arguments, exit codes, and examples.';
      when_to_use : 'When you need definitive documentation on any NBS tool — the single source of truth for tool contracts.';
      keywords    : ('tools'; 'reference'; 'master'; 'usage'; 'arguments'; 'exit-codes');
    );

    (
      kind        : Document;
      name        : 'NBS Teams';
      path        : 'docs/team/nbs-teams.md';
      summary     : 'Supervisor/worker pattern for multi-agent AI work — fresh context, specific tasks, success criteria.';
      when_to_use : 'When understanding the teams architecture or deciding whether to use workers for a task.';
      keywords    : ('teams'; 'supervisor'; 'worker'; 'multi-agent'; 'pattern'; 'delegation');
    );

    (
      kind        : Document;
      name        : 'C Extension Performance';
      path        : 'terminal-weathering/concepts/c-extension-performance.md';
      summary     : 'Performance discipline for CPython C extensions — METH_FASTCALL over METH_VARARGS, measured overhead comparisons.';
      when_to_use : 'When writing or reviewing CPython C extensions to avoid the slow tutorial patterns.';
      keywords    : ('c-extension'; 'cpython'; 'METH_FASTCALL'; 'METH_VARARGS'; 'performance'; 'calling-convention');
    );

    (
      kind        : Document;
      name        : 'C++ to C Analysis';
      path        : 'terminal-weathering/concepts/cpp-to-c-analysis.md';
      summary     : 'Detailed analysis of patterns, build failures, and interop from a large-scale C++ to C conversion of a JIT compiler.';
      when_to_use : 'When planning or executing a large C++ to C conversion and need to learn from prior experience.';
      keywords    : ('c++'; 'c'; 'conversion'; 'analysis'; 'jit'; 'interop'; 'large-scale');
    );

    (
      kind        : Document;
      name        : 'C++ to C Build Failures';
      path        : 'terminal-weathering/concepts/cpp-to-c-build-failures.md';
      summary     : 'Catalogue of compiler and linker errors from C++ to C conversion with root causes, fixes, and prevention rules.';
      when_to_use : 'When hitting build errors during a C++ to C conversion — look up the exact error message.';
      keywords    : ('c++'; 'c'; 'build'; 'errors'; 'linker'; 'compiler'; 'catalogue');
    );

    (
      kind        : Document;
      name        : 'C++ to C Checklist';
      path        : 'terminal-weathering/concepts/cpp-to-c-checklist.md';
      summary     : 'Mechanical yes/no checklist to run before compiling a converted C++ file for the first time.';
      when_to_use : 'Before compiling any file that was converted from C++ to C — prevents known failure classes.';
      keywords    : ('c++'; 'c'; 'checklist'; 'pre-compile'; 'verification'; 'mechanical');
    );

    (
      kind        : Document;
      name        : 'C++ to C Types';
      path        : 'terminal-weathering/concepts/cpp-to-c-types.md';
      summary     : 'Honest type definitions for the C++ to C porting vocabulary — BuildFailureClass, ConversionPattern, and related types.';
      when_to_use : 'When reading the companion C++ to C documents and need the formal type definitions.';
      keywords    : ('c++'; 'c'; 'types'; 'honest'; 'definitions'; 'vocabulary'; 'formal');
    );

    { --- docs/chat-architecture/ --- }

    (
      kind        : Document;
      name        : 'Chat Architecture Overview';
      path        : 'docs/chat-architecture/README.md';
      summary     : 'Reading-order index for the NBS chat system architecture — file formats, cursors, bus events, sidecar, and archiving.';
      when_to_use : 'When you need to understand the chat system and want to know which document to read first.';
      keywords    : ('chat'; 'architecture'; 'overview'; 'index'; 'reading-order'; 'system');
    );

    (
      kind        : Document;
      name        : 'Chat File Format';
      path        : 'docs/chat-architecture/chat-file.md';
      summary     : 'Specification of the .chat file format — header fields, base64-encoded messages, wire format, atomic writes, and locking.';
      when_to_use : 'When you need to understand the on-disk format of chat files or debug message encoding issues.';
      keywords    : ('chat'; 'file'; 'format'; 'header'; 'base64'; 'wire'; 'locking');
    );

    (
      kind        : Document;
      name        : 'Cursor System';
      path        : 'docs/chat-architecture/cursors.md';
      summary     : 'Per-agent read tracking via .chat.cursors files — how sidecars determine unread messages and notify agents.';
      when_to_use : 'When debugging why an agent is not seeing new messages or is processing old ones.';
      keywords    : ('cursor'; 'read-tracking'; 'unread'; 'position'; 'sidecar'; 'notification');
    );

    (
      kind        : Document;
      name        : 'Control Files';
      path        : 'docs/chat-architecture/control-files.md';
      summary     : 'Minimal-format control files for sidecar resource discovery, team coordination, and process tracking.';
      when_to_use : 'When you need to understand the control registry, pause file, or PID file formats.';
      keywords    : ('control'; 'registry'; 'pause'; 'pid'; 'sidecar'; 'discovery');
    );

    (
      kind        : Document;
      name        : 'Archive and Truncation';
      path        : 'docs/chat-architecture/archive.md';
      summary     : 'Auto-archiving when chat files exceed 2000 messages — archive naming, cursor survival, and terminal detection.';
      when_to_use : 'When understanding how old messages are preserved or debugging archive-related cursor issues.';
      keywords    : ('archive'; 'truncation'; 'threshold'; 'cleave'; 'history'; 'auto-archive');
    );

    (
      kind        : Document;
      name        : 'Sidecar Notifications';
      path        : 'docs/chat-architecture/sidecar.md';
      summary     : 'The sidecar monitoring loop — tick model, prompt detection, notification injection, interrupt handling, and periodic triggers.';
      when_to_use : 'When understanding how the sidecar detects idle prompts and injects notifications into agent sessions.';
      keywords    : ('sidecar'; 'notification'; 'monitoring'; 'tick'; 'prompt'; 'injection'; 'interrupt');
    );

    (
      kind        : Document;
      name        : 'Session Metadata';
      path        : 'docs/chat-architecture/session-metadata.md';
      summary     : 'Honest-format specification for .nbs/sessions/<handle>.honest — agent session state written by nbs-claude at launch.';
      when_to_use : 'When you need to understand the session metadata file format or debug session resume behaviour.';
      keywords    : ('session'; 'metadata'; 'honest'; 'transport'; 'launch'; 'resume');
    );

    (
      kind        : Document;
      name        : 'Bus Recovery';
      path        : 'docs/tools/nbs-bus-recovery.md';
      summary     : 'How agents recover bus context after starting or restarting — fresh start vs reconnect, event replay, and ack state.';
      when_to_use : 'When an agent restarts and needs to recover its bus subscription state without missing or replaying events.';
      keywords    : ('bus'; 'recovery'; 'restart'; 'replay'; 'ack'; 'context');
    );

    (
      kind        : Document;
      name        : 'Team Kill Reference';
      path        : 'docs/tools/nbs-team-kill.md';
      summary     : 'Reference for nbs-team-kill — clean-slate process termination for a team: sidecar-loops, sidecars, sessions, and PID cleanup.';
      when_to_use : 'When you need to kill all team processes before a full restart or to clear process leaks.';
      keywords    : ('team'; 'kill'; 'process'; 'clean'; 'shutdown'; 'reference');
    );

    (
      kind        : Document;
      name        : 'Team Status Reference';
      path        : 'docs/tools/nbs-team-status.md';
      summary     : 'Reference for nbs-team-status — process audit showing sessions, sidecars, sidecar-loops with duplicate and orphan detection.';
      when_to_use : 'When diagnosing duplicate sidecars, orphan processes, or verifying clean process state.';
      keywords    : ('team'; 'status'; 'process'; 'audit'; 'duplicate'; 'orphan'; 'reference');
    );

    (
      kind        : Document;
      name        : 'Bus Events';
      path        : 'docs/chat-architecture/bus-events.md';
      summary     : 'The .nbs/events/ file-based event queue — publish, ack, prune lifecycle with priority levels and @mention extraction.';
      when_to_use : 'When understanding how bus events flow between agents or debugging event delivery issues.';
      keywords    : ('bus'; 'events'; 'queue'; 'priority'; 'mention'; 'publish'; 'ack');
    );

    { --- docs/framework/ --- }

    (
      kind        : Document;
      name        : 'Why NBS';
      path        : 'docs/framework/Why-NBS.md';
      summary     : 'The philosophical foundation of NBS — bullshit as indifference to truth, and falsifiability as the antidote.';
      when_to_use : 'When explaining why NBS exists or introducing someone to its epistemic principles.';
      keywords    : ('why'; 'philosophy'; 'bullshit'; 'truth'; 'falsifiability'; 'foundation');
    );

    (
      kind        : Document;
      name        : 'Framework Overview';
      path        : 'docs/framework/overview.md';
      summary     : 'The problem NBS solves — plausibility vs truth in AI collaboration, and how externalised epistemic discipline closes the gap.';
      when_to_use : 'When you need a concise explanation of the NBS framework and its failure-mode taxonomy.';
      keywords    : ('overview'; 'framework'; 'epistemic'; 'plausibility'; 'structure'; 'failure-modes');
    );

    (
      kind        : Document;
      name        : 'NBS Document Tools';
      path        : 'docs/framework/nbs-doc.md';
      summary     : 'Guide to the three document tools — nbs-doc-analyse, nbs-doc-plan, and nbs-doc-describe — and when to use each.';
      when_to_use : 'When deciding which document tool to use for analysis, planning, or articulation.';
      keywords    : ('document'; 'tools'; 'analyse'; 'plan'; 'describe'; 'writing');
    );

    (
      kind        : Document;
      name        : 'Style Guide';
      path        : 'docs/framework/STYLE.md';
      summary     : 'Internal voice and writing style reference for NBS framework materials — scientist-theologian voice, short sentences, no mystification.';
      when_to_use : 'When writing or reviewing NBS framework documentation to maintain consistent voice and tone.';
      keywords    : ('style'; 'voice'; 'writing'; 'internal'; 'tone'; 'principles');
    );

    (
      kind        : Document;
      name        : 'Wiki Style Guide';
      path        : 'docs/framework/WIKI_STYLE.md';
      summary     : 'Style rules for wiki pages and technical articles — TL;DR first, tables for clarity, no fluff.';
      when_to_use : 'When writing wiki pages or technical articles for the NBS framework.';
      keywords    : ('wiki'; 'style'; 'article'; 'structure'; 'format'; 'technical');
    );

    (
      kind        : Document;
      name        : 'Investigation Mode';
      path        : 'docs/framework/investigation.md';
      summary     : 'How to run a hypothesis-driven side quest — branch convention, falsifiable claim narrowing, and evidence production.';
      when_to_use : 'When planning an investigation to answer a specific question through experiment rather than speculation.';
      keywords    : ('investigation'; 'hypothesis'; 'branch'; 'experiment'; 'side-quest'; 'evidence');
    );

    (
      kind        : Document;
      name        : 'The Pillar System';
      path        : 'docs/framework/pillars.md';
      summary     : 'The seven concept documents that anchor the NBS framework — goals, falsifiability, rhetoric, bullshit detection, standards, coordination, and PTE.';
      when_to_use : 'When you need to understand the conceptual foundations and how the framework prevents agent drift.';
      keywords    : ('pillars'; 'concepts'; 'foundation'; 'drift'; 'reference'; 'anchors');
    );

    (
      kind        : Document;
      name        : 'NBS Review';
      path        : 'docs/framework/nbs-review.md';
      summary     : 'How /nbs works — dynamic dispatch based on git branch and context, auditing reasoning quality and falsification discipline.';
      when_to_use : 'When understanding what the /nbs review command checks and how it routes to different review modes.';
      keywords    : ('review'; 'nbs'; 'dispatch'; 'reasoning'; 'quality'; 'drift'; 'audit');
    );

    (
      kind        : Document;
      name        : 'The Skill System';
      path        : 'docs/framework/skill-system.md';
      summary     : 'How NBS skills work — markdown files in claude_tools/ become slash commands via template expansion, symlinks, and Claude Code discovery.';
      when_to_use : 'When understanding how skills are installed, discovered, or when creating a new skill.';
      keywords    : ('skill'; 'system'; 'slash-command'; 'template'; 'symlink'; 'install'; 'discovery');
    );

    (
      kind        : Document;
      name        : 'NBS Audit';
      path        : 'docs/framework/nbs-audit.md';
      summary     : 'How /nbs-audit works — automated codebase audit against engineering standards with parallel sub-agents and adversarial TDD.';
      when_to_use : 'When understanding the audit process, its differences from /nbs review, or planning a codebase audit.';
      keywords    : ('audit'; 'codebase'; 'standards'; 'violations'; 'TDD'; 'automated');
    );

    (
      kind        : Document;
      name        : 'Discovery and Recovery';
      path        : 'docs/framework/discovery.md';
      summary     : 'Two-phase process for disordered projects — read-only discovery maps the territory, recovery rebuilds from the map.';
      when_to_use : 'When onboarding to a project with no epistemic structure and you need to understand before changing anything.';
      keywords    : ('discovery'; 'recovery'; 'archaeology'; 'onboarding'; 'disordered'; 'restructure');
    );

    (
      kind        : Document;
      name        : 'Noeomics Style Guide';
      path        : 'docs/framework/NOEOMICS_STYLE.md';
      summary     : 'Writing style for Noeomics — claims early, images as argument, difficulty matched to truth, morality named not hidden.';
      when_to_use : 'When writing or reviewing Noeomics material to maintain the distinctive voice and epistemic standards.';
      keywords    : ('noeomics'; 'style'; 'writing'; 'voice'; 'claims'; 'morality');
    );

    (
      kind        : Document;
      name        : 'Chat Colour Theme';
      path        : 'docs/framework/colour-theme.md';
      summary     : 'Design document for the 256-colour theme used by nbs-chat-terminal and nbs-chat-edit — canvas philosophy and colour space mapping.';
      when_to_use : 'When modifying or understanding the terminal colour scheme for chat tools.';
      keywords    : ('colour'; 'theme'; '256-colour'; 'terminal'; 'design'; 'xterm');
    );

    { --- docs/team/ --- }

    (
      kind        : Document;
      name        : 'Pythia Role';
      path        : 'docs/team/nbs-pythia.md';
      summary     : 'Pythia oracle design — periodic, stateless trajectory and risk assessment from the decision log, posted as a structured checkpoint.';
      when_to_use : 'When understanding how Pythia works, what she checks, or when tuning checkpoint frequency.';
      keywords    : ('pythia'; 'oracle'; 'trajectory'; 'risk'; 'checkpoint'; 'decision-log');
    );

    (
      kind        : Document;
      name        : 'Scribe Role';
      path        : 'docs/team/nbs-scribe.md';
      summary     : 'Scribe design — persistent memory layer that distils chat decisions into a structured log surviving compaction and restarts.';
      when_to_use : 'When understanding how institutional memory works or debugging decision log issues.';
      keywords    : ('scribe'; 'memory'; 'decision'; 'log'; 'persistent'; 'institutional');
    );

    (
      kind        : Document;
      name        : 'Help When Stuck';
      path        : 'docs/team/help-when-stuck.md';
      summary     : 'Symptom-to-fix troubleshooting guide for common agent and team problems — unresponsive agents, stale cursors, dead sidecars.';
      when_to_use : 'When an agent or team component is misbehaving and you need a quick diagnosis.';
      keywords    : ('help'; 'stuck'; 'troubleshooting'; 'symptom'; 'diagnosis'; 'fix');
    );

    (
      kind        : Document;
      name        : 'Tripod Architecture';
      path        : 'docs/team/tripod-architecture.md';
      summary     : 'The three-legged foundation of NBS teams — Scribe (memory), Bus (events), and Chat (delivery) — and why removing any leg collapses the system.';
      when_to_use : 'When understanding the architectural dependencies between Scribe, Pythia, Bus, and Chat.';
      keywords    : ('tripod'; 'scribe'; 'bus'; 'chat'; 'architecture'; 'oracle'; 'foundation');
    );

    (
      kind        : Document;
      name        : 'Generalist Role';
      path        : 'docs/team/nbs-generalist.md';
      summary     : 'Generalist design — implementation worker that receives tasks from the supervisor, executes with evidence, and reports outcomes.';
      when_to_use : 'When understanding the generalist role, her responsibilities, or how she receives and reports work.';
      keywords    : ('generalist'; 'worker'; 'implementation'; 'task'; 'execute'; 'report');
    );

    (
      kind        : Document;
      name        : 'Gatekeeper Role';
      path        : 'docs/team/nbs-gatekeeper.md';
      summary     : 'Gatekeeper design — pre-push review agent applying five criteria (correctness, location, secrets, completeness, consistency) with binary verdicts.';
      when_to_use : 'When understanding the gatekeeper review process or her five review criteria.';
      keywords    : ('gatekeeper'; 'review'; 'pre-push'; 'criteria'; 'correctness'; 'secrets');
    );

    (
      kind        : Document;
      name        : 'Theologian Role';
      path        : 'docs/team/nbs-theologian.md';
      summary     : 'Theologian design — architecture advisor who maps invariants, flags risks as falsifiable predictions, and guides design with evidence.';
      when_to_use : 'When understanding the theologian role or her approach to architectural analysis and risk identification.';
      keywords    : ('theologian'; 'architecture'; 'invariant'; 'risk'; 'design'; 'advisor');
    );

    (
      kind        : Document;
      name        : 'Testkeeper Role';
      path        : 'docs/team/nbs-testkeeper.md';
      summary     : 'Testkeeper design — test suite owner who writes falsifiable tests and benchmarks, proves things wrong, and does not write production code.';
      when_to_use : 'When understanding the testkeeper role or the falsification discipline applied to test suites.';
      keywords    : ('testkeeper'; 'test'; 'falsification'; 'benchmark'; 'ownership'; 'suite');
    );

    (
      kind        : Document;
      name        : 'Shepard Role';
      path        : 'docs/team/nbs-shepard.md';
      summary     : 'Shepard oracle design — ephemeral team dynamics assessor that checks agent liveness and posts coordination recommendations.';
      when_to_use : 'When understanding how team dynamics are assessed or tuning the shepard checkpoint schedule.';
      keywords    : ('shepard'; 'oracle'; 'team'; 'dynamics'; 'coordination'; 'liveness');
    );

    (
      kind        : Document;
      name        : 'Librarian Role';
      path        : 'docs/team/nbs-librarian.md';
      summary     : 'Librarian oracle design — ephemeral helper that unsticks agents by finding relevant prior decisions and recommending tools.';
      when_to_use : 'When understanding how the librarian helps stuck agents or when tuning her periodic schedule.';
      keywords    : ('librarian'; 'oracle'; 'helper'; 'decisions'; 'unstick'; 'knowledge');
    );

    (
      kind        : Document;
      name        : 'Supervisor Role';
      path        : 'docs/team/nbs-supervisor.md';
      summary     : 'Supervisor design — goal-keeper who decomposes terminal goals into tasks, delegates to agents, and monitors outcomes.';
      when_to_use : 'When understanding the supervisor role, task delegation patterns, or terminal goal maintenance.';
      keywords    : ('supervisor'; 'goal'; 'delegate'; 'task'; 'coordinate'; 'terminal-goal');
    );

    (
      kind        : Document;
      name        : 'Medic Role';
      path        : 'docs/team/nbs-medic.md';
      summary     : 'Medic design — continuous hallucination detector that cross-references agent claims against session logs and posts warnings.';
      when_to_use : 'When understanding how the medic verifies claims or debugging false hallucination warnings.';
      keywords    : ('medic'; 'hallucination'; 'monitor'; 'verify'; 'claims'; 'warning');
    );

    (
      kind        : Document;
      name        : 'Fixup Role';
      path        : 'docs/team/nbs-fixup.md';
      summary     : 'Fixup design — ephemeral immune system that diagnoses permanent agent health, repairs broken agents, and posts a team status summary.';
      when_to_use : 'When understanding the fixup self-repair mechanism or debugging agent restart failures.';
      keywords    : ('fixup'; 'repair'; 'immune'; 'diagnose'; 'restart'; 'health');
    );

    { --- docs/getting-started/ --- }

    (
      kind        : Document;
      name        : 'First Session';
      path        : 'docs/getting-started/03-first-session.md';
      summary     : 'Hello world walkthrough — launch a session, watch agents plan and work, shut everything down.';
      when_to_use : 'When running your first NBS team session and need step-by-step instructions.';
      keywords    : ('getting-started'; 'tutorial'; 'first'; 'launch'; 'session'; 'walkthrough');
    );

    (
      kind        : Document;
      name        : 'How the Team Works';
      path        : 'docs/getting-started/04-how-the-team-works.md';
      summary     : 'Explains the team structure — who does what, how work is scoped, and how the team avoids drift.';
      when_to_use : 'After your first session, when you want to understand the roles, task scoping, and coordination patterns.';
      keywords    : ('team'; 'roles'; 'structure'; 'scoping'; 'drift'; 'getting-started');
    );

    (
      kind        : Document;
      name        : 'Communication';
      path        : 'docs/getting-started/05-communication.md';
      summary     : 'How agents communicate — the chat terminal, @mentions, interrupts, and the constraint that agents cannot preempt each other.';
      when_to_use : 'When learning the communication model, @mention syntax, or the chat terminal interface.';
      keywords    : ('communication'; 'chat'; 'mention'; 'interrupt'; 'terminal'; 'getting-started');
    );

    (
      kind        : Document;
      name        : 'Oracles';
      path        : 'docs/getting-started/06-oracles.md';
      summary     : 'The four ephemeral oracles — Librarian, Pythia, Shepard, Fixup — why they are ephemeral and how they prevent groupthink.';
      when_to_use : 'When learning what oracles do, how they are triggered, and why they are spawned fresh each time.';
      keywords    : ('oracles'; 'ephemeral'; 'librarian'; 'pythia'; 'shepard'; 'fixup');
    );

    (
      kind        : Document;
      name        : 'Troubleshooting';
      path        : 'docs/getting-started/07-troubleshooting.md';
      summary     : 'Symptom-to-fix troubleshooting for new users — dead agents, unresponsive chat, cursor desyncs, and common startup failures.';
      when_to_use : 'When something goes wrong with your team and you need a quick fix.';
      keywords    : ('troubleshooting'; 'symptom'; 'fix'; 'debug'; 'startup'; 'getting-started');
    );

    (
      kind        : Document;
      name        : 'Terminal Operator Tutorial';
      path        : 'docs/getting-started/terminal-tutorial.md';
      summary     : 'Hands-on tutorial for operating the chat terminal — sending messages, searching history, controlling agents, spawning oracles.';
      when_to_use : 'When learning to operate the chat terminal after your team is running.';
      keywords    : ('terminal'; 'tutorial'; 'operator'; 'search'; 'commands'; 'interactive');
    );

    (
      kind        : Document;
      name        : 'Getting Started Index';
      path        : 'docs/getting-started/index.md';
      summary     : 'Reading-order index for the getting started guide — chapters 1-3 get you running, 4-6 explain how things work.';
      when_to_use : 'When starting with NBS and need to know what to read first.';
      keywords    : ('index'; 'getting-started'; 'reading-order'; 'guide'; 'chapters');
    );

    { --- docs/tools/ (key docs) --- }

    (
      kind        : Document;
      name        : 'Testing Strategy';
      path        : 'docs/tools/testing-strategy.md';
      summary     : 'Testing philosophy for non-deterministic AI output — AI evaluates AI, with explicit criteria replacing string matching.';
      when_to_use : 'When designing tests for AI-generated output or NBS tool behaviour.';
      keywords    : ('testing'; 'strategy'; 'non-deterministic'; 'AI'; 'evaluation'; 'criteria');
    );

    (
      kind        : Document;
      name        : 'Chat Terminal Reference';
      path        : 'docs/tools/nbs-chat-terminal.md';
      summary     : 'Full reference for nbs-chat-terminal — the human operator terminal with line editing, slash commands, agent restart, and background polling.';
      when_to_use : 'When you need details on chat terminal features, slash commands, or startup options.';
      keywords    : ('chat-terminal'; 'operator'; 'slash-commands'; 'polling'; 'restart'; 'reference');
    );

    (
      kind        : Document;
      name        : 'Spawn Worker Pipeline';
      path        : 'docs/tools/nbs-spawn-worker.md';
      summary     : 'The worker spawn pipeline — the one path from chat terminal to running Claude that survives double-fork, setsid, and PTY allocation.';
      when_to_use : 'When debugging worker spawn failures or understanding why alternative spawn methods fail.';
      keywords    : ('spawn'; 'worker'; 'pipeline'; 'double-fork'; 'setsid'; 'pty');
    );

    (
      kind        : Document;
      name        : 'Remote Development Tools';
      path        : 'docs/tools/nbs-remote.md';
      summary     : 'Reference for the four remote tools — nbs-remote-run, nbs-remote-read, nbs-remote-edit, nbs-local-run — routing through nbs-ts-helper for credentials.';
      when_to_use : 'When working on remote machines from the sandbox and need to choose the right remote tool.';
      keywords    : ('remote'; 'tools'; 'ssh'; 'sandbox'; 'credentials'; 'reference');
    );

    (
      kind        : Document;
      name        : 'File Browser Reference';
      path        : 'docs/tools/nbs-file-browser.md';
      summary     : 'Reference for nbs-file-browser — keys, file type dispatch, colour coding, /file integration, and directory memory.';
      when_to_use : 'When understanding the file browser features or its integration with the chat terminal.';
      keywords    : ('file'; 'browser'; 'bat'; 'viewer'; 'navigate'; 'reference');
    );

    (
      kind        : Document;
      name        : 'SSH Bridge Reference';
      path        : 'docs/tools/nbs-ssh-bridge.md';
      summary     : 'Reference for nbs-ssh-bridge — SSH ControlMaster multiplexing, setup behaviour, master lifecycle, and relationship to nbs-remote tools.';
      when_to_use : 'When understanding SSH connection multiplexing or configuring persistent master connections.';
      keywords    : ('ssh'; 'bridge'; 'remote'; 'multiplexing'; 'ControlMaster'; 'reference');
    );

    (
      kind        : Document;
      name        : 'Interactive Testing Guide';
      path        : 'docs/tools/interactive-testing.md';
      summary     : 'Guide to testing Claude Code behaviour requiring multi-turn interaction, permission prompts, and AskUserQuestion via nbs-ts.';
      when_to_use : 'When writing tests that need to respond to Claude Code prompts or simulate multi-turn conversations.';
      keywords    : ('interactive'; 'testing'; 'multi-turn'; 'prompt'; 'permission'; 'nbs-ts');
    );

    (
      kind        : Document;
      name        : 'Sidecar Reference';
      path        : 'docs/tools/nbs-sidecar.md';
      summary     : 'Full reference for the sidecar daemon — lifecycle, main loop tick model, prompt detection, notification injection, and self-healing.';
      when_to_use : 'When understanding sidecar internals, debugging notification delivery, or tuning monitoring intervals.';
      keywords    : ('sidecar'; 'daemon'; 'monitor'; 'tick'; 'notification'; 'self-heal');
    );

    (
      kind        : Document;
      name        : 'Chat System Reference';
      path        : 'docs/tools/nbs-chat.md';
      summary     : 'Full reference for nbs-chat — file-based messaging with base64 encoding, atomic writes, cursor tracking, and no privilege model.';
      when_to_use : 'When you need implementation-level details on the chat system beyond the architecture docs.';
      keywords    : ('chat'; 'reference'; 'implementation'; 'encoding'; 'atomic'; 'wire-format');
    );

    { --- concepts/ (missing) --- }

    (
      kind        : Concept;
      name        : 'Verification Cycle';
      path        : 'concepts/verification-cycle.md';
      summary     : 'The Design-Plan-Deconstruct-Test-Code-Document cycle — safety from verbs not nouns, with entry and exit criteria per phase.';
      when_to_use : 'When planning work phases or when someone skips testing because the types look right.';
      keywords    : ('verification'; 'cycle'; 'phases'; 'testing'; 'safety'; 'verbs');
    );

    (
      kind        : Concept;
      name        : 'Zero-Code Contract';
      path        : 'concepts/zero-code-contract.md';
      summary     : 'The human-AI collaboration contract — the human specifies and validates, the AI implements and reports, neither trusts assertions without evidence.';
      when_to_use : 'When defining the boundary between human and AI responsibilities in a project.';
      keywords    : ('zero-code'; 'contract'; 'human-AI'; 'engineer'; 'machinist'; 'evidence');
    );

    (
      kind        : Concept;
      name        : 'Teams Concepts Index';
      path        : 'concepts/teams/README.md';
      summary     : 'Index of multi-agent team concepts that build on base NBS concepts — coordination patterns, shared practices, and team-specific guides.';
      when_to_use : 'When looking for team-specific concept documents beyond the base NBS pillars.';
      keywords    : ('teams'; 'concepts'; 'index'; 'multi-agent'; 'coordination'; 'practices');
    );

    (
      kind        : Concept;
      name        : 'Making Code Shareable';
      path        : 'concepts/teams/make-shareable.md';
      summary     : 'Phased guide for preparing a codebase for external review — assessment, cleanup, audit, testing, documentation, and upstream sync.';
      when_to_use : 'When preparing code for a PR, external review, or open-source contribution.';
      keywords    : ('shareable'; 'review'; 'PR'; 'cleanup'; 'phases'; 'external');
    );

    (
      kind        : Concept;
      name        : 'Team Audit Guide';
      path        : 'concepts/teams/team-audit-guide.md';
      summary     : 'Human-facing guide to team audit — zone-based codebase hardening with progressive TDD, documented assertions, and resumable progress.';
      when_to_use : 'When planning or running a team audit and need the human-oriented overview.';
      keywords    : ('team-audit'; 'guide'; 'zones'; 'TDD'; 'progressive'; 'hardening');
    );

    (
      kind        : Concept;
      name        : 'Team Audit Methodology';
      path        : 'concepts/teams/team-audit.md';
      summary     : 'Full team audit methodology — zone-based hardening that fixes cross-cutting issues missed by file-level audits, with integrated TDD and documentation.';
      when_to_use : 'When executing a team audit and need the detailed phase-by-phase methodology.';
      keywords    : ('team-audit'; 'methodology'; 'zones'; 'cross-cutting'; 'architecture'; 'hardening');
    );

    { --- Honest library docs --- }

    (
      kind        : Document;
      name        : 'Honest User Guide';
      path        : 'lib/honest/docs/user-guide.md';
      summary     : 'Tutorial introduction to reading, writing, and understanding Honest documents — the interchange format for humans, AI agents, and machines.';
      when_to_use : 'When learning Honest for the first time or need a tutorial-style introduction.';
      keywords    : ('honest'; 'user-guide'; 'tutorial'; 'format'; 'interchange'; 'learning');
    );

    (
      kind        : Document;
      name        : 'Honest Specification';
      path        : 'lib/honest/specs/honest-spec.md';
      summary     : 'The Honest Format Specification v1.0 — self-describing declarative interchange format with Pascal-based type definitions.';
      when_to_use : 'When you need the authoritative specification for Honest syntax, semantics, and wire format.';
      keywords    : ('honest'; 'specification'; 'format'; 'syntax'; 'semantics'; 'wire');
    );

    (
      kind        : Document;
      name        : 'Honest Documentation Index';
      path        : 'lib/honest/docs/index.md';
      summary     : 'Entry point for Honest library documentation — reading order and links to user guide, CLI reference, implementors guide, and testing.';
      when_to_use : 'When starting with the Honest library and need to know what to read first.';
      keywords    : ('honest'; 'index'; 'documentation'; 'navigation'; 'reading-order');
    );

    (
      kind        : Document;
      name        : 'Honest Implementors Guide';
      path        : 'lib/honest/docs/implementors-guide.md';
      summary     : 'How to build a conformant Honest parser and serialiser — grammar, edge cases, and compliance requirements.';
      when_to_use : 'When implementing an Honest parser in a new language or debugging parser conformance issues.';
      keywords    : ('honest'; 'implementor'; 'parser'; 'serialiser'; 'grammar'; 'conformance');
    );

    (
      kind        : Document;
      name        : 'Honest Python Library';
      path        : 'lib/honest/docs/python-library.md';
      summary     : 'Pure Python implementation of Honest — parse, serialise, and extract Honest documents with a Pythonic API.';
      when_to_use : 'When using Honest from Python scripts or automation.';
      keywords    : ('honest'; 'python'; 'library'; 'parse'; 'serialise'; 'API');
    );

    (
      kind        : Document;
      name        : 'Honest Testing Guide';
      path        : 'lib/honest/docs/testing.md';
      summary     : 'How to run, understand, and extend the Honest test suites — conformance tests, property-based tests, and fuzz targets.';
      when_to_use : 'When running Honest tests or adding test coverage for new parser features.';
      keywords    : ('honest'; 'testing'; 'conformance'; 'fuzz'; 'property-based'; 'suite');
    );

    (
      kind        : Document;
      name        : 'Honest Specification Addendum';
      path        : 'lib/honest/specs/honest-addendum.md';
      summary     : 'Addendum to the Honest specification — gap resolutions and clarifications arising from implementation experience.';
      when_to_use : 'When the main specification is ambiguous and you need clarification on edge cases.';
      keywords    : ('honest'; 'specification'; 'addendum'; 'gaps'; 'clarification'; 'edge-cases');
    );

    (
      kind        : Document;
      name        : 'Honest CLI Reference';
      path        : 'lib/honest/docs/cli-reference.md';
      summary     : 'Reference for the five Honest CLI tools — honest-parse, honest-get, honest-fmt, honest-build, and honest-extract.';
      when_to_use : 'When you need usage details, options, or examples for any of the Honest command-line tools.';
      keywords    : ('honest'; 'cli'; 'reference'; 'tools'; 'parse'; 'get'; 'fmt');
    );

    { --- Terminal Weathering --- }

    (
      kind        : Document;
      name        : 'Terminal Weathering Concepts Index';
      path        : 'terminal-weathering/concepts/index.md';
      summary     : 'Index of terminal weathering concept documents — reading order for methodology, C++ to C patterns, GDB debugging, and performance.';
      when_to_use : 'When navigating the terminal weathering concepts and need to know which document to read first.';
      keywords    : ('terminal-weathering'; 'index'; 'concepts'; 'reading-order'; 'navigation');
    );

    (
      kind        : Document;
      name        : 'Terminal Weathering Concepts README';
      path        : 'terminal-weathering/concepts/README.md';
      summary     : 'Brief pointer to the terminal weathering concepts directory and root index.';
      when_to_use : 'When landing in the concepts directory and need orientation.';
      keywords    : ('terminal-weathering'; 'readme'; 'concepts'; 'pointer');
    );

    (
      kind        : Document;
      name        : 'GDB Debugging Reference';
      path        : 'terminal-weathering/concepts/gdb-debugging.md';
      summary     : 'Worked examples of debugging NBS C components with GDB via nbs-local-session and nbs-remote-session. 13 real examples covering attach, crash analysis, breakpoints, memory inspection, reverse debugging, and interactive stepping.';
      when_to_use : 'When debugging a crash, memory corruption, or unexpected behaviour in any NBS C component. Read this before adding printf.';
      keywords    : ('gdb'; 'debug'; 'debugging'; 'segfault'; 'crash'; 'breakpoint'; 'core dump'; 'ASAN'; 'memory'; 'nbs-local-session'; 'watchpoint'; 'reverse'; 'stepping');
    );

    { --- docs/ root --- }

    (
      kind        : Document;
      name        : 'Documentation Index';
      path        : 'docs/index.md';
      summary     : 'Top-level index of all NBS framework documentation — getting started, framework philosophy, tools, team roles, and chat architecture.';
      when_to_use : 'When you need to find documentation and do not know which section to look in.';
      keywords    : ('index'; 'documentation'; 'top-level'; 'navigation'; 'sections'; 'overview');
    );

  );
);