# Yardmaster: LLM Documentation Library > Consulted by Claude Code (and the future in-app chat panel) when users ask "how do I X?" or "what is X?" about Yardmaster. ## Purpose: dual audience This library has **two readers**, and every entry is written for both: 1. **Agents with repo access** (Claude Code, subagents, the in-app chat panel): use these pages as the authoritative reference when they need to _do something_ in the code or explain a feature. 2. **Outside AIs with no repo access**: a user can copy any single page into ChatGPT, Claude.ai, or the phone web UI and get an accurate answer without ever cloning the repo. **Implications for authors**: - Each page must be **self-contained**: explain the feature in prose, not by reference. Don't say "see `X.ts`" without saying _what_ that file does. - Assume the reader has never seen the app. Describe the UI surface (what pill, which menu, which shortcut) and the user-visible behavior before going into code. - File-path references are still valuable: an agent _can_ open them, but the page must stand on its own for a reader who can't. - When a feature changes UX, update its page in the same PR. A silently-stale page is worse than a missing one because agents trust what the library says. **How to use**: search the table for your topic. If your question isn't covered, Claude Code will say "not in library" and then answer from general knowledge. | Feature | Summary | Link | | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Corpus session capture (remember what a project's sessions learned, for your team, for yourself, or both) | **Two independent per-project opt-ins**, both off by default, under **Edit project → More options**: "Contribute to the team corpus" (shared) and "Remember what I learn here, for me only" (private). Either, both or neither, and a lane-indicator line underneath says which corpus is which for you (if you are in no organisation, both switches land in the same private place). When a session is **archived** it is queued locally as ONE row regardless of lanes; a drain takes **one session every five minutes** (never on boot) and only then resolves the destinations: re-checking BOTH Lab features (`team-corpus`, `personal-corpus`), BOTH project toggles, and for the personal lane the five content-type switches and two source switches, plus signed-in, online and the daily AI budget. It builds a scrubbed transcript (last 200 messages, tail-capped at 12,000 chars) and asks a small model **once** for at most five claims of ≤500 chars each, each classified into one of five kinds and backed by a **verbatim quote (12 to 200 chars) from the transcript**: **one extraction and one charge no matter how many lanes are live**. **No real quote, no saved fact**: every quote is checked on the machine against the exact transcript the model saw (whitespace, curly quotes and the ellipsis character forgiven, case-sensitive otherwise), a claim whose quote is missing or not found is dropped and counted (`unprovenDropped` in the drain log), and the quote itself is never sent to either corpus nor stored. **Most sessions yield zero claims and that is the correct answer**; the prompt forbids padding to a quota. Personal writes carry the content type and a `source` of `agent`; team writes carry neither and stay unclassified forever. A claim the model could not classify is dropped from both lanes and counted (`unclassifiedDropped`). **People & relationships is the one content type that ships OFF**: the most sensitive thing the corpus can hold. There is deliberately **no toggle for the `user` source** (the settings type cannot express one). The two lanes never share a flag or a column, and slice 2b added **no second isolation predicate**: a personal claim is filtered by the same exact-match `workspace_id` shape team claims are, so it can never surface in a team read. **A personal claim is NOT written when it clears the ladder: it is queued locally for the user to approve**, and nothing reaches corpus-api until they say yes; a team claim is still written straight through. One coalesced inbox row ("12 things learned, waiting", never one per fact) opens a pane where the batch is **approved all** in one click, edited, or discarded: discard is provisional until submit, a failed write leaves the row pending to be asked about again, and a pending row never expires. After **three consecutive batches approved with nothing changed**, Yardmaster *offers* to skip review for that project; nothing automatic ever grants it, "Not now" retires the offer without granting it, and the same switch ("Skip my review for this project") sits in Edit project and is reversible. That switch is desktop-only: blocked on the mobile/web bridge and deliberately not a CLI route. A session is attempted at most 3 times then abandoned; a claim a corpus refuses (4xx) is dropped rather than retried while 5xx/transport faults retry, and one lane's drop does not stop the other. A session is dropped for good only when **neither** destination wants it; turning a Lab feature off pauses instead (rows accrue). **Already-captured claims are not retracted by turning anything off**, and there is no personal-corpus browse/remove panel yet (the review step above is where an unwanted personal fact is caught, before it is ever stored). **Both lanes are now shipped**: a per-project toggle is the only switch either has, with no Lab gate on either side, so unticking a project's switches is what stops (and drops) its captures. Contracts: corpus-session-capture-contract, personal-corpus-review-queue-contract, personal-corpus-tenancy-contract. | [corpus-session-capture.md](corpus-session-capture.md) | | Team Corpus tokens (access keys for the shared team knowledge corpus) | Settings → Team Corpus mints, lists and revokes `crp_` access tokens that let another tool (Cursor, Claude Desktop, a script) read from and contribute to your team's shared knowledge corpus as you, without handing it your Yardmaster login. Mint takes a label (required, ≤120 chars, the only way to tell two tokens apart later); an **org admin** additionally gets a "Mint for a teammate" email field, and the resulting *delegate* token carries that teammate's identity while the corpus records separately which admin issued it. The plaintext is shown **exactly once** in a reveal dialog (focus lands on Copy, not the close X) and is erased the moment that dialog closes, never persisted, logged, toasted, or sent to the phone/web client. Tokens **never expire** (no `expires_at` column, on purpose: a silently-expiring credential inside another tool reads as "the corpus is broken" days later), so the row's **Last used / Never used** line is the only staleness signal and revoke is the only kill switch. Revoke is one-way (`revoked_at = COALESCE(revoked_at, now())`), confirm-dialog gated, never undoable; revoked tokens stay listed with a red pill. A failed load keeps the previous list and shows the error above it: it never renders "no tokens" on an error. Shipped: the section is there for every user, and the same list is mirrored in the Team Corpus panel under Setup → Tokens for other tools. Contract: team-corpus-token-contract. | [team-corpus-tokens.md](team-corpus-tokens.md) | | Team Corpus panel (govern what your team's agents have published) | The reading-and-governing half of the team corpus, opposite corpus session capture's writing half: an **Agent Tools → Team Corpus** sidebar row whose default view is a **needs-attention queue**: the **disputed** claims and the **stale** ones, not the full list (that is a second tab). Each claim carries who published it, which agent wrote it, when, and a tier (corroborated / confirmed / **disputed** / unverified); disputed is the one that matters, because a disputed claim is a wrong answer waiting to be cited by the next agent. Two human-only actions: **clear a flag** (erases a colleague's recorded objection, team-visible, takes an optional note) and **remove a claim** (**irreversible**, and Yardmaster refuses a blank or whitespace-only reason because that reason is the only surviving record of the removal). Neither is exposed as a CLI route: an agent that could unflag could erase the objection to its own mistake, and one that could redact could delete the evidence of it. **Desktop-only, reads included**: every corpus-governance channel is blocked on the mobile/web bridge and refused again in the handler, because a listing is the whole workspace's recorded knowledge in plain text, so the row and panel are hidden in browser mode rather than shown and then failing. Shipped: the row is there for every user, with no Lab toggle. The panel has two views: **Claims** (the queue above) and **Setup** (workspace, members incl. corpus-only invites, access tokens, and which projects contribute). | [team-corpus-panel.md](team-corpus-panel.md) | | Personal Corpus panel (read, search and prune your own recorded memory) | The one place a person sees their OWN private lane, as opposed to the team's: an **Agent Tools → Personal Corpus** sidebar row with three tabs, beside Team Corpus but deliberately not a lane tab inside it: two different consents, two different audiences, and two different verbs (you *govern* what your team published, you *own* what is recorded about you). **My corpus** carries **two lists, not one filtered list**: browsing the cloud is **free** and is the only place a claim can be opened or pruned, while **search costs one embedding call per query**, so it fires on Search/Enter and **never while you type**. A search **replaces** the list and says so, because a semantic search is not a subset of the page you were looking at and a thin result would otherwise read as a thin corpus; its hits are **read-only**, arriving as the same id-less projection an agent sees, so nothing there could open or remove a claim. **Review** is the queue of claims an agent proposed. **Add** writes a claim by hand and it goes **straight into the lane, never through Review**: the queue exists to put a human between an agent's guess and the corpus, and the person typing is already that human; the reply distinguishes **added** / **agreed with something already there** / **already recorded word for word**, because reporting all three as "added" would claim a write that did not happen. **Prune is irreversible**: the wording is erased, a typed reason is required (it is the only surviving record), and a separate confirm (safe answer **Keep it**) stands between the person and the delete, because a reason box is an argument to the call, not an answer to "are you sure". **Desktop-only, reads included** (search twice over, since it also spends), and **permanently CLI-routeless for add and remove**: an agent that could add would forge the owner's own attribution, and one that could remove could delete the evidence of its own mistake. **Shipped**: the row is there for everyone, with nothing to switch on; signed out, the panel says so rather than showing an empty list. | [personal-corpus-panel.md](personal-corpus-panel.md) | | Personal corpus over MCP (reach your private corpus from Cursor or Claude Desktop) | The corpus service exposes an **MCP endpoint** (`/mcp`) that Cursor, Claude Desktop or any MCP client reaches with a `crp_` corpus token, and a connected client sees **four** tools: `corpus_search`, **`personal_search`**, `corpus_write`, `corpus_flag`: four rather than three is the quickest confirmation the client is on a current service. `personal_search` reads **your** private lane and only ever yours; it takes `query` / optional `scope` / `limit` and **no argument that names a lane, workspace, user or author** (the lane is derived from the identity on the token, so there is nothing for an agent to fill in wrongly), and deliberately no `minTier` (a personal claim has one author forever, so the filter would look like it worked and always return nothing). **Fail-closed by design: a credential reads a personal corpus only if it was minted FROM that personal corpus.** A team-lane token gets a written refusal, never an empty result: the copy shouts "NOTHING WAS SEARCHED" and instructs the agent not to tell the user their corpus is empty, because a confident false statement about data the agent was never allowed to see is the failure mode that matters. Consequence: a user with **no organisation** mints a personal-lane token and both search tools read the same lane (synonyms); an **org member** mints a team-lane token and `personal_search` refuses it, and there is currently **no way** for an org member to mint a personal-lane token, a deliberate future change rather than something to work around. Cursor config is `.cursor/mcp.json` with `"Authorization": "Bearer ${env:CORPUS_TOKEN}"` (never a literal token: Cursor interpolates `${env:…}` in `url` and `headers`); Claude Desktop needs the `npx mcp-remote` stdio bridge with `Authorization:${AUTH_HEADER}` **without a space** (Windows Claude Desktop / Cursor / Codex CLI mangle spaces inside `args`), since remote servers added by hand to `claude_desktop_config.json` are ignored and connector headers are a beta, org-admin-entered capability. Tokens never expire, so **revoke is the only kill switch**: the manual checklist ends by revoking and confirming the next call fails rather than falling back to an unauthenticated read. Reachability split honestly: automated over the real HTTP door with a real token (`corpus-api/tests/mcp-route.test.ts`), manual for the two desktop clients. | [personal-corpus-mcp.md](personal-corpus-mcp.md) | | Personal corpus seed (what a new session already knows about you) | When you start a session, Yardmaster folds **at most five** of your own standing notes into the very first thing the agent reads, so it begins already knowing how you work. Chosen by **kind first** (preferences, then code & conventions, then decisions, then project facts), then best-corroborated first, then newest first, with an id tiebreak so the same notes always produce the same five. **There is deliberately no relevance matching**: a lexical gate was built and measured and scored **0.0000 on all eight** fixtures where a note should have been picked, so it would have discarded every note that mattered (design §10.3); the five-note cap is what bounds the cost of being wrong instead. Never seeded: notes about **other people**, anything **disputed**, anything the service has marked **stale**, anything from a **team** corpus, and anything whose lane is **unknown** (unknown is never read as personal). Nothing survives the rules → nothing is added at all, never an empty block. Every rendered line is `- [tier] note` under a preamble that says the tag is how well corroborated it is and that the notes are *not* selected for relevance: the protection against an `unverified` note being restated as fact. **Invisible and unblocking**: the block rides the outgoing prompt only (your chat bubble is exactly what you typed), and any failure costs the session its notes, never its existence. **Every spawn path** (slice 3c): a Claude session started with a prompt, a blank session seeded when you send its first message, a session resumed or recovered after a crash (re-reading the corpus as it stands that day, not as it stood when the session began), the first message to a non-Claude engine, and launching a session that already exists. Reads the **local copy** of the corpus, never the cloud, so nothing is fetched while you wait, and a newly approved note can be **up to fifteen minutes** behind. **No switch of its own, and since the feature shipped there is no feature switch either: the seed cannot be turned off.** What you control is what is there to seed: capture is a per-project opt-in that starts off, nothing is stored without your approval, and a stored note can be pruned. Contracts: personal-corpus-seed-contract, personal-corpus-cache-contract. | [personal-corpus-seed.md](personal-corpus-seed.md) | | Corpus tools in your sessions (how your agents look things up and propose new facts) | Every Claude session Yardmaster starts gets **two MCP tools**: `corpus_search` (look something up in your corpus mid-session, before assuming a preference or re-asking what you already settled) and `corpus_remember` (**propose** a fact for it). Results come back tagged `- [tier \| lane \| age] note`, personal notes outranking team ones, because an agent restating an unverified note as fact is the failure the tags exist to stop. **`corpus_remember` never saves**: it queues for your review and its own reply says so in words ("It is NOT in the corpus yet… Do not tell them it has been remembered"), so an agent cannot honestly report it as stored: the review queue, surfaced as the same single coalesced inbox row as automatic capture, is the **only** door into the corpus. A session may propose at most **10** facts, counted whether or not you approve them, so approving does not hand it fresh slots. **No per-project opt-in and nothing to configure**: the tools appear automatically once the Personal Corpus feature is on **and** you are signed in, and when either is false they are absent AND the instruction line naming them is withheld, because a session told about a tool it does not hold will invent the result. There is **no argument naming a lane, user or workspace**: identity comes from who is signed in, and a body that tries to name one is refused. **An empty result is normal and is not an error** ("Nothing stored yet that matches. Carry on without it; this is not an error."), and a corpus outage returns the same sentence with a success status, so a failure costs the agent a lookup rather than your turn, with the honest consequence that an agent cannot distinguish "empty" from "down". Anything a search surfaced is remembered per-session and filtered out of that session's own capture, so the corpus cannot re-file its own answers and mistake repetition for corroboration. Not the same as the `corpus_search` Cursor/Claude Desktop see (that one is the remote `/mcp` endpoint with a `crp_` token); these carry no token you manage. **Shipped**: the only remaining condition is being signed in. Contract: personal-corpus-agent-access-contract. | [personal-corpus-agent-access.md](personal-corpus-agent-access.md) | | Session Event Log (troubleshoot one session: its lifecycle events) | A per-session view (the **Events** option on a session's All/Agent/You message filter, in the "⋯" overflow menu) that lists only that session's lifecycle events (auth-token refreshes, Claude-account switches (naming which account → which), restart/crash recovery, pauses, snoozes, compaction), hiding the chat and the high-volume `subagent-result` tool output. Account switches show the accounts' human names resolved live from OPAQUE account ids stored on the event (never the email/label), so sharing/exporting a session can't leak an account address; an unresolvable (removed) account degrades to generic wording. Reuses the existing session-history feed (no new data channel; works on mobile/web, which loads full history on open). v1 names the common rate-limit / load-balance moves; a rarer silent respawn-time move is listed but unnamed. Contract: session-event-log-contract. | [session-event-log.md](session-event-log.md) | | Deploy Profiles (tell the AI which account to deploy a project under) | Named, reusable bundles of service→account mappings (Google/Firebase-gcloud, Vercel, Netlify, Render, AWS, or free-text Other) that tell an AI which cloud account to deploy a project under. Create/edit in Settings → Access & Sharing → Deploy Profiles; assign one per project via the Deploy Profile picker under Edit/Add Project → **More options** (hidden for virtual projects). On session spawn Yardmaster injects a `## Deploy Profile` system-prompt block with per-service CLI hints (`firebase login:use`, `vercel --scope`, `export AWS_PROFILE`, …) via `--append-system-prompt`, so the agent verifies the right account before deploying. Stores only **non-secret identifiers** (never credentials/tokens) and is advisory guidance, not a hard account switch. Persisted in SQLite (migration v125: `deploy_profiles` + `deploy_profile_entries` + `projects.deploy_profile_id`, ON DELETE SET NULL); profile name is not unique (find-or-create); editing deletes-and-reinserts entries. Fully shipped (not Lab-gated). Assigning a profile routes over `PATCH /project/:id`; profile CRUD is desktop-only. | [deploy-profiles.md](deploy-profiles.md) | | User Management (owner/admin-only org admin console) | Owner/admin-only console for an Yardmaster **organization**: part of the optional cloud Global Auth identity layer that is OFF on installs without the sign-in gate, so the whole section is absent unless the gate is on. Once signed in, the Settings row shows for **every** user, but its label + contents are role-shaped: a global owner/admin sees the full **User Management** console described here; a plain member sees the same row labeled **Workspaces**, opening only the self-serve workspace surface (list + switcher + Create). Settings → User Management (Accounts & AI / Team & Admin group), three tabs: **Users**, **Access Requests** (amber pending badge), **Workspace**. Invite one or bulk-invite by email, approve/deny join requests, change **role** (owner/admin/member/trial) or **tier** (enterprise/pro/starter/free), enable/disable/delete accounts, and assign Team Chat workspace membership (org_admin/member). Self-protection: you can't change/disable/delete your own row. The nav-row role check is only cosmetic; the real boundary is server-side: every op calls `assertCallerIsAdmin()` then a token-verifying Cloud Function that re-verifies admin from cryptographically-verified Firebase ID-token claims (`manage_users` needs role ≥ admin). Deleting removes the profile doc, not the Firebase Auth login. The core console is NOT a Lab/in-development feature: gated purely by role. Cloud-backed (Firebase). Also documents the **self-serve workspaces** layer (`self-serve-workspaces`, shipped 2026-07-19): a paid-tier user creates/owns their own workspace, switches the active one, sees a config-driven mock **Pricing** screen (no payment flow), and a workspace owner/admin gets a scoped roster. All-Firebase by owner decision (2026-07-17), membership subcollection is authority. | [user-management.md](user-management.md) | | API Usage explorer (admin console: spend by user/feature/provider/model/endpoint over time) | Super-admin **API Usage** tab in the hosted admin console (beside AI Spend; owner/admin-of-the-fleet only, never an org-admin) that breaks down pooled-**gateway** AI usage/spend from the `gateway_usage` per-call log by **user · feature · provider · model · endpoint**, with a **daily (UTC) spend trend**, a window picker (7/30/90d, default 7), and **click-a-row drill-down** that filters the WHOLE view (totals + trend + every breakdown) to one slice: the cross-tab (e.g. a user's spend by model over time; stack filters to narrow). Two lenses in one screen: per-user consumption + per-feature company spend. One bounded `createdAt`-window scan (doc-capped; surfaces a truncation banner so a partial total isn't mistaken for complete), exact integer-micro money, in-memory drill-down filters (no new Firestore index). Adds ONE new datum: the gateway now records a sanitized `model` per proxied call (both lanes), **forward-only** (older calls show `(unknown)`; every other dimension works on existing history immediately). v1 measures spend + call count, not token volume. Going live is a gateway → functions → dashboard deploy, each approval-gated (the pipeline never deploys). Contract: ai-admin-console I20. | [admin-api-usage.md](admin-api-usage.md) | | Agent Permission Level (how much agents do before Yardmaster asks) | A global setting (Read-only / Guarded / Autonomous / Full trust) gating Yardmaster's Claude permission gatekeeper, plus an optional per-chat override on top. read_only asks before any write/command; guarded (new-install default) auto-edits INSIDE the project but asks before shell commands, config-file EDITS, and out-of-project writes; autonomous auto-edits+commands in-project; full = legacy auto-approve-everything. A dangerous-file denylist (SSH keys, creds, /etc/passwd, shell rc) and email-session lockdown sit ABOVE every level, global or per-chat, and no level relaxes them; only Full Send (a per-chat, in-memory, human-only mode from the Allow arrow or Chat permissions, behind a warning, with a red badge, cleared on close/archive/restart) skips the denylist ask, never the email/sweep/confined/plan-lock rails. New installs default guarded; EXISTING installs are pinned ONCE to full on upgrade (no sudden prompt wave), never overriding a later choice. Set in a new onboarding "Agent Access" step and Settings → Workflow (dropdown above the Auto-Approve toggles). Any single chat can also carry its own level (set via the Allow arrow's "Allow everything in this chat", or the ⋯ menu's "Chat permissions"), shown by a chip/shield only when different from global, human-set and human-reset only, never inherited by a new chat. Governs Claude(-compatible) sessions only: Cursor/Gemini/Codex keep their own permission models. The approval card shows the command being gated; approving runs it verbatim. Reads (incl. config reads) are always allowed at guarded. | [agent-permission-level.md](agent-permission-level.md) | | Offline banner (network-connectivity indicator) | A slim amber bar across the top of the app that appears when your computer loses its internet connection ("You are offline. Some features are unavailable." + Wi-Fi-off icon), so a failing session or stalled sync reads as your network, not Yardmaster. Always on, no setting. Driven by a main-process connectivity service that polls `net.isOnline()` every 10 s (2 s while offline) and emits `NETWORK_STATUS_CHANGED` on a transition; the renderer debounces ~5 s (`useOfflineBannerGate`) so a transient blip never flashes it. This is the "that's your network" job the Anthropic status monitor defers to. | [offline-banner.md](offline-banner.md) | | Anthropic outage alerts (API status monitor) | Watches Anthropic's official public status feed (status.claude.com summary JSON: the page behind status.anthropic.com) and tells you when an Anthropic incident is what's failing your Claude sessions, so you never check the status page by hand. Polls every 5 min (60s during an incident) AND checks instantly the moment a session fails with a transient Anthropic API error (rate-limited, Anthropic-account sessions only). A relevant incident (Claude API / Claude Code components; claude.ai-web-only incidents filtered out) raises ONE deduped inbox card whose primary button is **View status page** (shown alongside the universal "Start session"), fires ONE desktop notification, and drops one "likely their outage, not your setup" note into each failing session's chat; when Anthropic resolves it (2 clean polls: flap-guarded) the card auto-archives + a "resolved" notification fires. Dismissing the card sticks across restarts (only a genuinely NEW incident re-raises). Never alerts about the status page being unreachable (that's your network: the offline banner's job). On by default; Settings → Notifications → Anthropic outage alerts (`anthropicStatusMonitorEnabled`); inert in e2e/sandbox instances. | [anthropic-status-monitor.md](anthropic-status-monitor.md) | | New models arrive automatically (central model catalog, formerly the new-model watcher) | The owner's own Yardmaster watches every provider (Claude, Codex, Gemini, GPT, DeepSeek, Kimi, GLM, MiniMax, Meta), confirms price from two sources, sends one tiny test message, and publishes the model to a live list; every install reads that list every few hours and shows the model in the Model picker under "Newly released" as "New model, added automatically", already priced, with no app update and no inbox card. Add-only over built-in models (never removes, relabels or reprices one), last-good cache when offline, the owner can remove a model, a daily data-only PR bakes the list into each release. Settings → Notifications shows a read-only line instead of the "New model alerts" toggle while the Live model catalog feature is on; with it off, the original per-install watcher (one deduped inbox card per new model, Add it for me, Use it now) still runs. | [new-model-watcher.md](new-model-watcher.md) | | Kimi balance monitor (low-balance + auto-recharge alerts) | Opt-in background watcher (OFF by default) that polls your Moonshot (Kimi) prepaid balance and covers two surprises: (a) raises ONE deduped inbox card + desktop/phone notification with a one-click **Recharge** button (opens platform.moonshot.ai) when your available balance drops below your threshold, before Kimi sessions start failing with "insufficient balance"; and (b) a SEPARATE deduped "Kimi balance auto-recharged" card (with a **Manage billing** button) when the balance **jumps UP** between checks, the tell-tale of a silent linked-card auto-recharge that billed you, which the low-balance alert can never catch (auto-recharge keeps the balance above the low mark). Checks ~every 4h via Moonshot's free balance API (no AI tokens, $0), only when the feature is on AND a Kimi key is set; a failed fetch skips the tick (never a false alert); the balance baseline persists across the 4h gap AND an app restart, and the first-ever poll only seeds the baseline. Threshold is user-set ($5 default, $0 to $10,000; $0 disables the check). Deduped so it never nags; re-fires if you go low again after recharging. Settings → Notifications → Kimi balance monitor (`kimiBalanceMonitorEnabled` / `kimiBalanceThresholdUSD`); kill switch `AMC_DISABLE_KIMI_BALANCE_MONITOR`; inert in e2e/sandbox. | [kimi-balance-monitor.md](kimi-balance-monitor.md) | | Gate-health monitor (dev-only: catches Yardmaster's freeze-prevention gates silently degrading) | A dev-only background watchdog (a no-op in packaged builds, like the gates it watches) that every ~15 min verifies Yardmaster's agent-command freeze-prevention gates are installed + current (the search-admission shims + managed ripgrep config at `~/.amc/bin`, the npm/npx/pnpm command-pacing shims, the per-session Windows process cap, the `~/.bashrc` fork-storm guards, and shell-snapshot freshness) and raises ONE deduped, dismissible inbox alert per silently-degraded gate, naming the gate + the fix (restart to reinstall / remove an overriding env var / clear stale shell snapshots) with a one-click **Open Troubleshooting** button. At most one alert per gate per day (survives restart + dismiss), auto-clears on recovery. Load-gated (skips its tick when the box is hot), fail-open throughout (a read error never alerts; an intentionally-disabled gate is reported disabled, not degraded), and anti-drift-locked so it can't false-alarm on healthy shims. Observes + alerts only, never throttles anything, never caps session count (the prime directive). Kill switch `AMC_DISABLE_GATE_HEALTH_MONITOR=1`; inert in e2e/sandbox. | [gate-health-monitor.md](gate-health-monitor.md) | | "Code was updated" notice (dev-mode runs: reload or restart after the checkout moves) | In developer-mode runs (`npm run dev` from a git checkout; the installed app is unchanged), Yardmaster watches the checkout's HEAD with fs.watch (never polling git) and, when it moves to a new commit under the running app, raises ONE dismissible inbox card plus one toast: **Reload window** when only window code changed, **Restart app** (the existing confirm-then-restart dev path) when `src/main`, `src/preload`, `src/shared`, the root package.json, a lockfile or an electron/vite config changed, or when git could not tell. A newer commit replaces the card; going back to the start commit clears it. Never reloads or restarts by itself; buttons are desktop-only. Kill switch `AMC_DISABLE_DEV_CODE_UPDATED_NOTICE=1`. Contract: dev-code-updated-notice-contract. | [dev-code-updated-notice.md](dev-code-updated-notice.md) | | Cloud fleet testing regime (how heavy verification is offloaded to a scale-to-zero cloud fleet) | Developer/infrastructure reproduction guide (not an end-user feature, no in-app setting) for how Yardmaster offloads heavy verification (unit tests, typecheck, lint, builds, real-browser E2E) to a **scale-to-zero Google Cloud fleet** so dozens-to-100+ concurrent agents never freeze the box (the prime directive: slow the agents, never the user). Covers three planes + a health layer: the VM fleet (Windows + Linux `e2-standard-4` pools, mostly Spot with a non-preemptible on-demand core, name-derived zone spread, golden images, idle self-shutdown + a liveness-aware disk reaper), the **GCS-bucket-as-queue** control plane (no server, $0 idle, kill-proof; CAS-claimed jobs, the object protocol, and the exit-code contract where infra failures 64/65/75 can NEVER masquerade as a failing test, a per-lockfile immutable env cache, and thin git bundles cut against a shared master pointer), the client routing gate (`--cloud`, the machine-wide toggle cascade, RAM/CPU/disk admission brakes, and the fail-open ladder queue→legacy→local), the legacy SSH/IAP fallback (and why it drove the move to the queue), and the cloud-side canaries + heartbeat watchdogs that watch from OUTSIDE the dev box and page only on a sustained outage. Ends with the transferable reliability patterns, a phased reproduction checklist, and the cost model. Written so another engineer can build a similar regime; internal test-locked invariants live in `.claude/memory/cloud-test-offload.md` + the `cloud-test-offload-contract.md` / `cloud-queue-contract.md` contracts. | [cloud-fleet-testing-regime.md](cloud-fleet-testing-regime.md) | | JLS Image Studio (removed 2026-07-26) | Removed in the fork strip commit `33b4c4633`: the embedded JLS Image Studio sidebar tab no longer exists. The page states what was removed and what to use instead. | [jls-image-studio.md](jls-image-studio.md) | | Convert files between formats (on-device, agent-callable) | On-device file-format conversion any Yardmaster agent can call: PDF→Markdown, DOCX→PDF, images (PNG/JPEG/WebP/GIF/TIFF/SVG/AVIF, HEIC→JPEG/PNG) + image→PDF, audio/video (MP4→MP3, video↔GIF, video frame-grab, MKV/AVI, FLAC/Ogg/Opus/AAC/AIFF), data (CSV↔JSON↔YAML, CSV→table), spreadsheets (Excel xlsx↔csv/json, xlsx→md/html), subtitles (SRT↔VTT). Agent-first via `POST /convert` plus a spawn-prompt shim that teaches every spawned session it can convert files; writes a NEW file next to the original (never overwrites: suffixes on a clash), runs locally at **$0** with no AI tokens, bounded by input-size + timeout caps. Documents/images/subtitles work out of the box (HEIC via a bundled WASM codec); audio/video need system ffmpeg (humanized "install from Settings → Toolchain" when absent). A one-click **PDF→Markdown** UI exists in project docs (right-click → keep-both/replace) + chat attachments, plus a full user-facing **File Converter** tool (in development, gated `fileConverterEnabled`, toggle in Settings → Optional Features) opened from the toolbar to drag/pick a file and convert to any supported format (desktop writes next to the original + **Open** the result in-app or in the OS default app & **Show in folder**, allow-list-gated; mobile downloads). The File Converter also has a desktop-only **Download from web** mode: paste a URL (YouTube/Vimeo/direct link) and `yt-dlp` saves it to Downloads as Video (MP4) / Audio (MP3) / Best (UI-only, no agent/CLI route; needs yt-dlp + ffmpeg from Settings → Toolchain). Per-conversion **quality/size options** (image quality/resize, audio bitrate, video resolution: a `/convert` `options` field, or the UI's Options panel) and desktop **batch** convert (drop many files → one target → convert all) are supported. Conversion takes a local file (no URL inputs); legacy `.xls`/`.ods` and pptx **inputs** are not supported. | [file-conversion.md](file-conversion.md) | | Run a file from chat (right-click a runnable path → Run / Run as administrator) | When a chat message mentions a runnable file by its path (e.g. a PowerShell fix script `` `C:\tmp\amc-excl-fix-j.ps1` ``), right-click the path → **Run** or **Run as administrator** to launch it without copying it into a terminal. A confirmation dialog shows the EXACT path first (paths can be AI-written); the file then runs in a terminal window that stays open. Admin uses the OS's own prompt (Windows UAC / macOS password): Yardmaster can't bypass it. Runnable set: Windows `.ps1/.bat/.cmd/.exe/.com/.msi`, macOS `.sh/.command/.app` (menu matches the host OS; desktop-only, not from the phone client). For programs/installers a left-click REVEALS the file in its folder instead of running it (running is right-click-only); scripts left-click to a read-only preview. Injection-proof launch (Windows `-EncodedCommand`, macOS two-layer escaping, no shell); the launched window outlives Yardmaster; deliberately works for files anywhere on disk (the gate is your confirm + the OS prompt, not a folder restriction). | [run-files-from-chat.md](run-files-from-chat.md) | | Mermaid diagrams (render diagrams in chat) | A ```mermaid fenced block in a chat message renders as an actual diagram (flowchart / sequence / state / class / etc.) instead of raw text, theme-matched, horizontally scrollable, with a hover view-source toggle + copy. While a reply is still streaming it shows the source and draws the diagram once the turn settles; a broken or oversized diagram falls back to the source text so nothing is lost. Untrusted-safe: rendered in mermaid `strict` mode AND SVG-sanitized before display. The same shared `MermaidDiagram` engine also draws the file-explorer `.mmd` preview and the Mind Map "View as Mermaid" panel. Always on; no setting. | [mermaid-diagrams.md](mermaid-diagrams.md) | | Unreleased-feature gating (hide in-development features until they ship) | Developer/agent mechanism: a central registry + a single visibility gate keep an in-development feature hidden by default, revealed only when a developer marks it `shipped`, launches with `AMC_SHOW_=1`, or flips its **Settings → Lab** toggle; a CI test guarantees "visible-by-default if and only if shipped". Ships one example, a "🧪 Labs" badge in the projects-sidebar header. NOT a security boundary: it controls UI visibility only, so an unsafe in-development feature still needs its own backend guard. | [unreleased-feature-gating.md](unreleased-feature-gating.md) | | Drive Yardmaster (watch & steer an AI operating Yardmaster's UI: dev/QA tool) | A developer tool that boots a VISIBLE, isolated sandbox Yardmaster and points a Claude session at it to operate the real UI toward a goal you type (clicking, navigating, toggling, exercising features), narrating each step in its chat so you watch beside the app and steer via the composer (the cockpit is just the popped-out driving session window next to the headed sandbox window). Sandbox-only and fails closed (the driver attaches only to the sandbox CDP endpoint and refuses unless instanceId=claude-sandbox, so it physically can't touch your real install); free navigation/settings by default, spawning a real sandbox session is a separate per-run cost-gated opt-in. Invoked explicitly as `/drive-amc `; a dev/QA tool, never a shipped end-user feature. | [drive-amc-cockpit.md](drive-amc-cockpit.md) | | Stuck-task helper (get unstuck when you keep snoozing the same thing) | Notices when you snooze the SAME session / email / PR / message three separate times and drops one dismissible Inbox card ("Want a hand getting unstuck?") that starts a short AI chat pre-briefed about the stuck item; it interviews you about the resistance (unclear / too big / boring / blocked / nervous) and helps you take a tiny first step. A durable per-item counter survives the snooze→return cycle; offered once per item (ever) and capped at ONE active card at a time so a bulk snooze can't flood the Inbox; never nags; dismiss-snoozes and active-snooze edits don't count. The coach reuses the instant-greeting deferred Super-Prompt launch (not the wellness AI-Coaching feature). In-development: reveal via Settings → Lab toggle or `AMC_SHOW_STUCK_TASK_HELPER=1`. | [stuck-task-helper.md](stuck-task-helper.md) | | Local Chat (chat with a local model via Ollama) | A gated "Chat" area to converse with an AI model running locally on your PC via Ollama: free, private, offline, no API key or account. A first-run wizard detects Ollama (one-click Download if missing), scans your RAM to recommend a model (✅ runs great / ⚠️ slow / 🚫 too big), downloads it with a progress bar, then drops you into a streaming chat with saved, renamable conversations. Plain-text only; no tools or file access (that's what coding sessions are for); never silently falls back to a paid cloud model. In-development: reveal via Settings → Lab toggle or `AMC_SHOW_LOCAL_CHAT=1`. | [local-chat.md](local-chat.md) | | Web-app verification (functionally test a web app you build, via Obscura) | Gives a coding-session agent a single `verify_web_app` tool that functionally checks a web app it built (does it load, are key elements present, does navigation/forms work, any console errors) by running real `playwright-core` against Obscura, a lightweight Rust headless browser, instead of full Chrome. Functional only: no screenshots / visual checks (Obscura has no rendering engine). Opt-in + installed on demand; the tool appears only on web-app projects when Obscura is installed and the capability is enabled. In-development: reveal via Settings → Lab toggle or `AMC_SHOW_WEBAPP_VERIFY=1`. | [web-app-verification.md](web-app-verification.md) | | Chrome Extension Dev (build and test a Chrome extension autonomously, via agent-browser) | When a project is a Chrome extension (has a `manifest.json` with `manifest_version` 2 or 3), equips the session with an extension-dev workflow that lets the agent load the unpacked extension into a real Chrome, click the popup, take screenshots, read the console, and reload after edits: building and testing without manual clicking. Requires the `agent-browser` CLI + Chrome-for-Testing (one-click "Set it up for me" install). Auto-writes a git-excluded `agent-browser.json` to the project root. Chrome only; no Firefox/Safari; no Chrome Web Store publishing. Includes a "Build a Chrome Extension" guided coaching mission. Privacy-safe: launches a clean managed Chrome, never your real profile. In-development: reveal via Settings → Lab toggle or `AMC_SHOW_CHROME_EXTENSION_DEV=1`. | [chrome-extension-dev.md](chrome-extension-dev.md) | | Decks (AI presentation builder) | A Gamma-style presentation builder built into Yardmaster: type a prompt and Claude drafts an outline, then generates slide cards across ~10 hand-designed layouts (title / text / split / bullets / two-column / full-bleed image / icon-grid / timeline / comparison / quote), themeable (Clean / Midnight / Ember / Paper). Uses your existing Yardmaster Claude login + cost tracking with a daily spend cap; renders in a native built-in virtual project beside the projects sidebar (NON-spawnable: no Claude session). In-development: reveal via Settings → Lab toggle or `AMC_SHOW_DECKS=1`. | [decks.md](decks.md) | | Recurring Special Events (birthdays/anniversaries/holidays → Google Calendar + reminders, in development) | In-development **tab inside the Google Calendar panel** ("Recurring Events"; gated via the `recurring-special-events` unreleased-feature: `recurringSpecialEventsEnabled` / `AMC_SHOW_RECURRING_SPECIAL_EVENTS=1` / Settings → Optional Features; desktop-only) for adding yearly occasions that fan out into **Google Calendar** events plus lead-time reminders. Three recurrence modes: a **fixed annual date** (e.g. June 13), an **Nth weekday of a month** (e.g. the 3rd Sunday of May), or a **built-in holiday** from a hardcoded catalog (Mother's/Father's Day, Memorial/Labor Day, Thanksgiving, Easter via Computus, Christmas, …). Each event creates a day-of entry plus any chosen lead reminders (day-of, a day before, a week before, a month before, or a **custom number of days before**) as separate visible calendar events, mirroring the user's original Birthday/Anniversary Reminder Sheet. Fixed-date reminders become single perpetual yearly-recurring Google events (RRULE); floating (nth-weekday / holiday) lead reminders are computed EXACTLY per year and materialized across a rolling multi-year horizon (topped up on panel load), so "10 days before Mother's Day" lands correctly every year even though the holiday moves. Reuses Yardmaster's existing Google Calendar integration (OAuth + `createEvent`, idempotent); desktop-only for the initial release; if Google isn't connected it prompts to connect in Settings. | [recurring-special-events.md](recurring-special-events.md) | | What Changed (unified cross-board PM activity feed, in development) | In-development unified PM activity feed (gated via the `pm-unified-feed` unreleased-feature, `pmUnifiedFeedEnabled` / `AMC_SHOW_PM_UNIFIED_FEED=1` / Settings → Lab toggle), surfaced as an Yardmaster built-in virtual project labeled "What Changed" (`__pm_unified_feed__`) docking in the main panel beside the projects sidebar: NON-spawnable (renders its own feed UI, hosts no Claude session). A cross-board activity timeline ranked by significance (static weights + recency / board / mention factors), with a board / time / type / actor filter bar, inline actions (mark done, open in board), deterministic per-entry summaries plus AI batch summaries of the visible events, and an 8 AM daily digest delivered as an inbox alert. Backed by a multi-filter + paginated query layer over the existing PM event stream. | [pm-unified-feed.md](pm-unified-feed.md) | | PM Intelligence Advisor (cross-board strategic advice + quick questions, in development) | In-development advisory intelligence layer for the AI Project Manager (gated via the `pm-intelligence-advisor` unreleased-feature, `pmIntelligenceAdvisorEnabled` / `AMC_SHOW_PM_INTELLIGENCE_ADVISOR=1` / Settings → Lab toggle), surfaced as an Yardmaster built-in virtual project labeled "PM Advisor" (`__pm_advisor__`) docking in the main panel beside the projects sidebar: NON-spawnable (renders its own UI, hosts no Claude session). Turns the PM Cross-Board Intelligence snapshots into actionable advice: strategic insights ranked by severity (resource conflicts, cascading delays, effort drift, seasonal risk, cross-department), strategic coaching, Monte-Carlo completion prediction narratives with what-if, automation policy recommendations, and a plain-English quick-question box grounded in the current board data (template-first, LLM-escalated per the PM AI comfort setting, daily-capped). The first panel wires the insights list + the quick-question box. | [pm-intelligence-advisor.md](pm-intelligence-advisor.md) | | Flowcharts (visual flowchart editor, in development) | In-development standalone visual flowchart editor (gated via the `flowchart` unreleased-feature, `flowchartEnabled` / `AMC_SHOW_FLOWCHART=1` / Settings → Lab toggle), surfaced as an Yardmaster built-in virtual project labeled "Flowcharts" that docks in the main panel beside the projects sidebar: mounted like Decks (`panelOwnsLayout` + `mobilePrefersPanel`, so it also works on a phone). Draw boxes + connectors on a React Flow canvas, drop shapes from a palette, organise them into swimlanes, keep a saved library, and export Mermaid (one-way). The editor's own Charts/Sessions tabs live inside the panel; the **Sessions** tab spawns AI sessions into the same `__flowchart__` project (resolver-mapped to `/flowchart-agent`) that can read + draw on the open board. A **Build with AI** entry (Charts empty-state + header) turns a one-line description into a whole chart: it starts a regular AI session (you pick the model) that builds the graph via the CLI, and Yardmaster auto-arranges the result. Stored as one graph blob (`{ nodes, edges, lanes }`) per row in the soft-deleted `flowcharts` table. | [flowchart.md](flowchart.md) | | Workflows (n8n/Zapier-style automation canvas, in development) | In-development visual automation builder (gated via the `workflows` unreleased-feature, `workflowsEnabled` / Settings → Lab toggle), surfaced as an Yardmaster built-in virtual project labeled "Workflows" docking in the main panel beside the projects sidebar (`__workflow__`, mirroring Flowcharts). A workflow is a trigger plus a DAG of steps (deterministic actions, branching if/else, and AI steps) that Yardmaster runs automatically once you approve it from the inbox (nothing executes silently); data flows between steps via `{{ NodeName.path }}` template references. Like Flowcharts, the panel has a Workflows | Sessions tab strip: the **Sessions** tab hosts AI build sessions in the same `__workflow__` project (spawnable + resolver-mapped); a **Build with AI** entry turns a plain-English description into a whole graph via a hidden CLI-driven primer, then stops for you to review + request approval. The underlying trigger/DAG-executor engine is documented separately: `.claude/memory/contracts/workflow-engine-contract.md`. | [workflows.md](workflows.md) | | Agent Email (your agent's own email address) | Give your agent a real Cloudflare-backed email address (`yardmailbox.com`), surfaced as a sidebar entry under Yardmaster → Agent Tools. Claim it by picking the name before the @ (live `name@yardmailbox.com` preview + instant validation); names are globally unique on the shared domain, reserved words are blocked, and the name is chosen once. Inbound mail starts or continues a session: receiving turns on automatically when you claim (no restart) with an on/off switch to pause it, gated by a "who can email it" control (Only me / approved senders / Anyone, default Only me; replies on an existing thread always pass); the agent can reply back out (per-account limits, no spoofing, bounce/complaint suppression). It's the primary way to receive email into Yardmaster; the older bring-your-own-inbox "Email Inbound" is now framed as an "Advanced" option. In-development: reveal via Settings → Lab toggle or `AMC_SHOW_AGENT_EMAIL=1`. | [agent-email.md](agent-email.md) | | Team Chat (built-in channels + DMs, a Slack replacement) | A built-in real-time team messenger inside Yardmaster: channels + direct messages delivered live to every device (desktop and phone) via the cloud, using your existing Global Auth identity (no separate account), plus fully self-serve workspaces you create yourself and share by a 10-char invite code (a separate Firestore-native tenant `chatWorkspaces/*` beside your governed company workspace in one switcher rail; server-gated join, chat-local roles only, no billing/claim coupling). Create public/private channels and 1:1/group DMs (addressed by a deterministic participant id, so a DM never forks), send with @mentions, optimistic send + offline queue (no double-posting), self-profile widget + manual availability overrides, presence + typing indicators, unread badges, and "load older" history. Self-serve workspace tiles can be given a custom gradient color (right-click or long-press) for visual distinction; an owner can **delete** a self-serve workspace with a **30-day undo** (soft-delete + Undo toast, then a scheduled reaper permanently erases it: F046). Renders as a native built-in virtual project beside the projects sidebar (NON-spawnable: no Claude session); the renderer talks to Firestore directly (not through Yardmaster IPC), authorized entirely by Security Rules. $0 of AI spend. Custom emoji: workspace admins upload party-parrot-style images (PNG/GIF/WebP ≤256 KB) with a `:shortcode:` that works in the emoji picker, reactions, custom status, and inline in message text. In-development: reveal via Settings → Lab toggle or `AMC_SHOW_TEAM_CHAT=1`. | [team-chat.md](team-chat.md) | | Workspace icon color (Team Chat workspace tile customization) | Right-click (or long-press on mobile) a self-serve Team Chat workspace tile to pick a gradient color from an 8-color palette (green, blue, red, purple, orange, pink, slate, teal); stored locally per device (localStorage). The active tile always shows the accent fill; custom colors appear on inactive tiles. "Remove color" resets to the default ring outline. Firestore has an `iconColor` field but server persistence is a follow-on. | [workspace-icon-color.md](workspace-icon-color.md) | | Approved senders for message channels (who can auto-start a session via SMS/Slack/Telegram) | A per-channel allowlist of who may **auto-start an AI session or run an automation** from an inbound SMS, Slack, or Telegram message. **Fail-closed: an empty list = nobody** (deliberately the opposite of the older Email Inbound box, which has its own secret-token gate), so an unknown texter or a stranger in a monitored Slack channel can't spin up a paid AI run before you've said who you trust. Blocked senders' messages still arrive in your inbox; only the automatic session/automation start is gated. Set it in Settings → Connections → Channels → SMS / Slack / Telegram (an **Approved senders** card of removable chips + an Add box). Because "empty = nobody" can pause an auto-start you relied on, the first block per channel (only if you have automations on) drops ONE Inbox note naming an example sender to add. Not a security wall (a phone number / Slack ID is spoofable: it's a convenience + cost guard). Closed security-sweep F018/F020/F021/F022/F026. | [inbound-sender-allowlist.md](inbound-sender-allowlist.md) | | Voiceprint Studio (build an email style guide in your voice) | An in-development sidebar panel that builds + sharpens an **email style guide**: the doc you paste into any AI to draft email in your voice ("voiceprint" = your WRITING voice, NOT audio/TTS). Four tabs: **Corpus** (pull your Gmail Sent folder; each email auto-guessed You/AI with the reason; confirm/flip), **Calibrate** (the AI re-drafts one of your real emails BLIND (it never sees your reply), then a 3-pane compare with optional blind mode; Nailed it / Off → note → the AI proposes one guide rule → Approve & save), **Style Guide** (the living, versioned guide), **Progress** (pass rate). The default profile seeds from AND mirrors approved fixes back to `~/Claude/johnny-email-voiceprint.md` (atomic write + .bak; reads on open, writes only on Save/Approve). Needs Gmail connected + an Anthropic key (graceful messages if missing); sent mail stored locally; the blind-draft context excludes your real reply (test-locked); never sends email. Reveal via Settings → Lab toggle or `AMC_SHOW_VOICEPRINT_STUDIO=1`. | [voiceprint-studio.md](voiceprint-studio.md) | | Dev Pipeline panel (oversee runs + timing/monitoring + worktrees + auto-approve gates + auto-lander + worktree cleanup) | A built-in sidebar panel that oversees the dev-pipeline workflow in one place: the live pipeline runs happening now (which step each is on and whether it's waiting at a gate, with a live `waiting