[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-microsoft-shadow-frog":3,"mdc-icx214-key":33,"related-repo-microsoft-shadow-frog":2849,"related-org-microsoft-shadow-frog":2887},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":11,"stars":22,"repoUrl":23,"updatedAt":24,"license":25,"forks":26,"topics":27,"repo":28,"sourceUrl":31,"mdContent":32},"shadow-frog","analyze codebases with shadow knowledge bases","Use a shadow knowledge base to understand any codebase. The .shadow\u002F directory mirrors the source tree with markdown files containing behavioral insights — known bugs, edge cases, implicit contracts, and user preferences. Always check the shadow before editing, debugging, or investigating code. When the user shares important context, write it to the shadow immediately. Invoke shadow-frog-init to create it, shadow-frog-update to refresh it, shadow-frog-dream for autonomous exploration, shadow-frog-meditate for shadow hygiene, or shadow-frog-viewer to browse it.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},"microsoft","Microsoft","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fmicrosoft.png",[12,16,19],{"name":13,"slug":14,"type":15},"Knowledge Management","knowledge-management","tag",{"name":17,"slug":18,"type":15},"Engineering","engineering",{"name":20,"slug":21,"type":15},"Code Analysis","code-analysis",13,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog","2026-07-07T06:53:24.688167",null,3,[],{"repoUrl":23,"stars":22,"forks":26,"topics":29,"description":30},[],"A suite of AI coding agent skills that build and maintain a shadow knowledge base for any codebase. ","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Ftree\u002FHEAD\u002Fskills\u002Fshadow-frog","---\nname: shadow-frog\ndescription: >-\n  Use a shadow knowledge base to understand any codebase. The .shadow\u002F\n  directory mirrors the source tree with markdown files containing\n  behavioral insights — known bugs, edge cases, implicit contracts,\n  and user preferences. Always check the shadow before editing,\n  debugging, or investigating code. When the user shares important\n  context, write it to the shadow immediately. Invoke shadow-frog-init\n  to create it, shadow-frog-update to refresh it, shadow-frog-dream\n  for autonomous exploration, shadow-frog-meditate for shadow hygiene,\n  or shadow-frog-viewer to browse it.\n---\n\n# ShadowFrog\n\n`.shadow\u002F` mirrors the source tree. Each source file has a `.md` shadow organized\nby symbol. Each symbol section contains discoveries — behavioral insights anchored\nto that code location.\n\n## Required Actions\n\n**Every time you work on code in a repo with `.shadow\u002F`:**\n\n1. **Read `_prefs.md` first** — it contains project-wide conventions,\n   user preferences, and things the user explicitly wants to avoid.\n   Violating a preference wastes the user's time.\n2. **Read `_cross\u002F` discoveries** — these are the highest-value findings,\n   spanning multiple files. List `_cross\u002F` and read any files whose titles\n   relate to the area you're working in. Cross-cutting discoveries reveal\n   hidden contracts, interaction bugs, and design patterns that per-file\n   shadows alone cannot capture.\n3. **Check `_dreams\u002F` for experiment results** — `_dreams\u002F_index.md` lists\n   autonomous exploration experiments. Read reports relevant to your task —\n   they contain verified bug analyses, attempted fixes, and architectural\n   insights. Dreams may contain knowledge not yet distilled into per-file\n   shadows, so always check when investigating a bug or unfamiliar area.\n4. **Before editing any file**: read its shadow (`.shadow\u002F\u003Cpath>.md`),\n   check `_cross\u002F` for cross-cutting discoveries about it, and apply\n   what you learn. The shadow contains known bugs, edge cases, and\n   implicit contracts discovered by previous sessions.\n   **Note**: `_index.md` discovery counts may be stale — always check\n   per-file shadows and `_cross\u002F` directly rather than relying solely on\n   the index summary.\n5. **When the user explains something about code** (gotcha, design intent,\n   warning, history): write a `source: user` discovery to the shadow\n   immediately. Do not ask where to put it — resolve the `file::symbol`\n   anchor yourself by searching `_index.md`, shadow files, and session\n   context (current file, recent edits).\n6. **When the user states a preference or convention** (not tied to any\n   specific file): write it to `_prefs.md` immediately.\n7. **After code changes**: run `\u002Fshadow-frog-update`\n\n## Directory Layout\n\n```\n.shadow\u002F\n  .shadowignore      Gitignore-syntax file for excluding paths from the shadow\n  _index.md          File list with symbol counts and discovery counts\n  _prefs.md          Project-wide user preferences (not tied to any file\u002Fsymbol)\n  _cross\u002F            Cross-cutting discoveries (span multiple files)\n    \u003Cslug>.md        One file per cross-cutting discovery (descriptive kebab-case name)\n  _meta\u002F\n    state.json       Last commit, timestamps, counts\n  _dreams\u002F           Dream experiment archive (detailed reports + diffs)\n    _index.md        Table of all experiments with verdicts\n    \u003CYYYYMMDD-HHMMSSZ-slug>\u002F      One folder per experiment\n      report.md      Structured report with YAML frontmatter\n      patch.diff     Full implementation diff against base_commit\n  \u003Cmirrored tree>\u002F   Per-file shadows\n    file.py.md       Organized by symbol\n```\n\n## Reference Notation\n\nCanonical format: `file_path::symbol_name`\n\nExamples: `src\u002Fauth.py::authenticate_user`, `src\u002Fauth.py::UserAuth.validate`,\n`src\u002Fauth.py` (file-level, no symbol)\n\nThe symbol name is the stable anchor.\n\n## Per-File Shadow Format\n\n```markdown\n# Shadow: src\u002Fauth.py\n\n**Language**: Python | **Lines**: 142 | **Last modified**: 2025-01-15\n\n## File-Level\n\n- This module has no __all__ — all top-level names are public.\n  _(verified, source: exploration)_\n\n## `class UserAuth`\n\n### `UserAuth.validate`\n\n- Catches ALL exceptions and returns False — swallows\n  connection errors, making network failures look like invalid tokens.\n  _(verified, source: exploration)_\n\n## `authenticate_user`\n\n- Silently returns None on expired tokens. Callers must check.\n  _(verified, source: exploration, labels: [bug])_\n  Also involves: `src\u002Fmiddleware.py::require_auth`\n\n## Cross-References\n\n- [db-connection-lifecycle](..\u002F_cross\u002Fdb-connection-lifecycle.md)\n  (involves `src\u002Fdb\u002Fconnection.py::ConnectionPool`, `src\u002Fapi\u002Froutes.py::get_user`)\n```\n\nHeading format (**hard rule — parsers depend on this**):\n- Top-level symbols (classes, functions, constants): `##` heading with symbol in backticks\n- Nested symbols (methods): `###` heading with symbol in backticks\n- `## Cross-References` — always last section\n\nThe viewer parser only matches the backtick form. A heading written as\n`### UserAuth.validate` (no backticks) will have its discoveries\nsilently dropped from search\u002Ftop output. Always wrap the symbol in\nbackticks, including for nested symbols.\n\nExamples:\n```\n## `authenticate_user`\n## `class UserAuth`\n### `UserAuth.validate`\n```\n\n## Cross-Cutting File Format (`_cross\u002F\u003Cslug>.md`)\n\n```markdown\n# Database connection lifecycle\n\n**Category**: pattern\n**Refs**:\n- `src\u002Fdb\u002Fconnection.py::ConnectionPool.get`\n- `src\u002Fauth.py::authenticate_user`\n- `src\u002Fapi\u002Froutes.py::get_user`\n\n**Discovery**: All database access goes through a connection pool that\nsilently reconnects on failure. First request after DB restart is slow (~2s).\n\n_(verified, source: exploration)_\n```\n\n## Preferences File (`_prefs.md`)\n\nProject-wide user preferences and conventions that are not tied to any\nspecific file or symbol. These guide all agent work across the codebase.\n\n```markdown\n# Preferences\n\n- No backward compatibility — only keep the latest code, no shims or aliases.\n  _(source: user)_\n\n- Use snake_case for all Python function and variable names.\n  _(source: user)_\n\n- Prefer small, focused PRs over large sweeping changes.\n  _(source: interaction)_\n```\n\nFormat:\n```\n- \u003Cpreference or convention>\n  _(source: \u003Cuser|interaction>)_\n```\n\nPreferences are always trusted (same rank as `source: user`). They don't\nneed `verified\u002Funcertain\u002Frefuted` — if the user said it, it's a directive.\n\nWhen to write to `_prefs.md` vs per-file shadow vs `_cross\u002F`:\n- Applies to the whole repo, no specific file → `_prefs.md`\n- Applies to a specific file or symbol → per-file shadow\n- Applies to 3+ specific files → `_cross\u002F\u003Cslug>.md`\n\n## Discovery Format\n\nPer-file discoveries (no IDs — anchored by their `file::symbol` heading):\n```\n- \u003Cbehavioral statement>\n  _(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>)_\n  Also involves: `file::symbol`, `file::symbol`\n```\n\nWith labels (optional — only when the discovery is actionable):\n```\n- \u003Cbehavioral statement>\n  _(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>, labels: [bug, security])_\n  Also involves: `file::symbol`\n```\n\nWith dream report link (optional — only for experiment-derived discoveries):\n```\n- \u003Cbehavioral statement>\n  _(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>)_\n  Dream report: `_dreams\u002F\u003Cdream-id>\u002F`\n```\n\nCross-cutting discoveries (one per `_cross\u002F\u003Cslug>.md` file):\n```\n# \u003CTitle>\n\n**Category**: \u003Ccategory>\n**Refs**:\n- `file::symbol`\n\n**Discovery**: \u003Cbehavioral statement>\n\n_(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>)_\n```\n\nSlug naming: use descriptive kebab-case derived from the title.\nExample: title \"Database connection lifecycle\" → filename `db-connection-lifecycle.md`\n\n### Labels\n\nLabels mark actionable discoveries so agents can quickly scan for specific\ntypes. Most discoveries are just knowledge — labels are only for findings\nthat call for action.\n\n| Label | Use when |\n|-------|----------|\n| `bug` | A defect that should be fixed |\n| `performance` | A bottleneck or inefficiency |\n| `security` | A vulnerability or unsafe pattern |\n| `feature-gap` | Missing functionality or improvement opportunity |\n| `tech-debt` | Code smell, duplication, refactoring opportunity |\n\nA discovery can have multiple labels: `labels: [bug, security]`.\nOmit labels entirely for pure observational knowledge.\n\nLabels go in the metadata line:\n```\n_(verified, source: exploration, labels: [bug])_\n```\n\nCross-cutting discoveries can also have labels — add them to the metadata line.\n\n### Fields\n\n- `verified|uncertain|refuted` — verification status\n- `source: exploration` — agent discovered via code analysis\n- `source: user` — human stated it in conversation\n- `source: interaction` — emerged from collaborative work (debugging, refactoring)\n- `labels: [...]` — optional, actionable labels (see table above)\n- `Also involves:` — `file::symbol` refs to other code locations (required if discovery touches other files)\n- `Dream report:` — optional, `_dreams\u002F\u003Cdream-id>\u002F` link for experiment-derived discoveries\n- `Category` (cross-cutting only): pattern, behavior, edge-case, contract, performance, intent, warning, history, convention\n\n## Trust Order\n\n1. `source: user` — highest trust, always `verified`\n2. `source: interaction` — always `verified`\n3. `verified` from exploration\n4. `uncertain` — not yet confirmed\n5. `refuted` — skip\n\n## Five Reference Links (all must be maintained)\n\n1. **File mapping**: `src\u002Fauth.py` ↔ `.shadow\u002Fsrc\u002Fauth.py.md`\n2. **Symbol anchoring**: every source symbol has a `##`\u002F`###` heading in its shadow\n3. **Also involves**: per-file discoveries list other `file::symbol` locations\n4. **Cross-ref back-pointers**: per-file `## Cross-References` links to `_cross\u002F\u003Cslug>.md` entries\n5. **Cross-cutting refs**: `_cross\u002F\u003Cslug>.md` `**Refs**:` lists all involved `file::symbol` locations\n\nLinks 4 and 5 are bidirectional: if `_cross\u002Fdb-connection-lifecycle.md` references\n`src\u002Fauth.py::fn`, then `src\u002Fauth.py.md` must list it in `## Cross-References`, and vice versa.\n\n## Seven Invariants\n\n1. Every included source file has exactly one shadow at `.shadow\u002F\u003Cpath>.md`\n2. Every symbol in source has a `##`\u002F`###` heading in its shadow\n3. Per-file discoveries touching other files have `Also involves:` with `file::symbol`\n4. Cross-ref back-pointers match: `_cross\u002F\u003Cslug>.md` refs ↔ per-file `## Cross-References`\n5. Every entry in `## Cross-References` has a corresponding `_cross\u002F\u003Cslug>.md` file\n6. Cross-cutting filenames are unique (enforced by filesystem)\n7. No duplicate discoveries (same behavioral claim at same symbol)\n\nTo audit a shadow for structural drift (invariant 3 format, invariants 4–5,\nplus enum and heading-format guards), locate the viewer script and run it:\n\n```bash\nVIEWER=\"\"\nfor DIR in .github\u002Fskills\u002Fshadow-frog-viewer .claude\u002Fskills\u002Fshadow-frog-viewer; do\n    [ -f \"$DIR\u002Fshadow-viewer.py\" ] && VIEWER=\"$DIR\u002Fshadow-viewer.py\" && break\ndone\npython3 \"$VIEWER\" --check-invariants\n```\n\nExits 0 if clean, 1 with one violation per line otherwise. Invariant 3 is\nchecked for anchor *format* only (not existence of the referenced file or\nsymbol); invariants 1, 2, and 7 require source parsing \u002F semantic match and\nare not statically checked; invariant 6 is filesystem-enforced.\n\n## Lookup Commands\n\n```bash\n# File's shadow\ncat .shadow\u002Fsrc\u002Fauth.py.md\n\n# Specific symbol's knowledge\ngrep -A 20 \"## \\`authenticate_user\\`\" .shadow\u002Fsrc\u002Fauth.py.md\n\n# Cross-cutting discoveries for a file\ngrep -rl \"src\u002Fauth.py::\" .shadow\u002F_cross\u002F\n\n# Search by topic\ngrep -rl \"error.handling\\|exception\" .shadow\u002F --include=\"*.md\"\n\n# All user-shared knowledge\ngrep -r \"source: user\" .shadow\u002F --include=\"*.md\"\n\n# Project-wide preferences\ncat .shadow\u002F_prefs.md\n\n# List all cross-cutting discovery files\nls .shadow\u002F_cross\u002F\n```\n\n## Verification\n\nTwo methods, use whichever fits the claim:\n\n**Observe-based** (for simpler claims — code reading suffices):\n1. Read the source code at the relevant `file::symbol`\n2. Trace the logic: does the behavioral claim hold?\n3. If confirmed → `verified`. If contradicted → `refuted`. If unclear → `uncertain`.\n\n**Do-based** (for harder claims — requires execution):\n1. Write a short verification script (test, assertion, or probe) that would\n   confirm or refute the claim\n2. Run it\n3. Based on the result → `verified` or `refuted`\n\nPrefer do-based for claims about runtime behavior, performance, error handling\npaths, or race conditions. Prefer observe-based for claims about code structure,\ntypes, or static properties.\n\n## Dedup and Writing Rules\n\nBefore writing any discovery, follow this procedure:\n\n1. **Read before write**: Read all existing discoveries under the target\n   `file::symbol`. If an existing discovery makes the same behavioral\n   claim (even if worded differently) → update the existing one. If the\n   new one extends an existing one → merge into a single richer entry.\n   If they conflict → investigate the code, keep the correct one, mark\n   the other `refuted`.\n2. **Append, don't replace**: If the symbol already has discoveries,\n   append your new one after them. If there is a `_No discoveries yet._`\n   placeholder, remove it and write your discovery. Never use the\n   placeholder as an edit anchor if it's already gone — read the file first.\n3. Write in canonical format (see Discovery Format above)\n4. **Fix bad format**: if you see any existing content that doesn't\n   follow the canonical format, fix it in place\n\nFor cross-cutting, search `_cross\u002F` for overlapping `**Refs**:` sets\nbefore creating a new entry. Only create `_cross\u002F\u003Cslug>.md` for\ndiscoveries spanning **3+ files** — otherwise use per-file entries with\n`Also involves:` references.\n\n## Related Skills\n\n- `\u002Fshadow-frog-init` — create `.shadow\u002F` for a new repo\n- `\u002Fshadow-frog-update` — refresh shadows after changes or from conversation\n- `\u002Fshadow-frog-dream` — autonomous exploration and experimentation while user is AFK\n- `\u002Fshadow-frog-meditate` — deduplicate, merge, and resolve conflicting discoveries\n- `\u002Fshadow-frog-viewer` — browse and query the shadow (overview, search, preferences, recent)\n",{"data":34,"body":35},{"name":4,"description":6},{"type":36,"children":37},"root",[38,47,68,75,91,277,283,295,301,312,341,346,352,857,869,909,922,927,936,949,1135,1147,1152,1275,1280,1289,1309,1327,1355,1361,1373,1382,1387,1396,1401,1410,1422,1431,1442,1449,1454,1566,1579,1584,1593,1598,1604,1707,1713,1779,1785,1905,1941,1947,2040,2045,2221,2234,2240,2553,2559,2564,2574,2618,2628,2658,2663,2669,2674,2733,2773,2779,2843],{"type":39,"tag":40,"props":41,"children":43},"element","h1",{"id":42},"shadowfrog",[44],{"type":45,"value":46},"text","ShadowFrog",{"type":39,"tag":48,"props":49,"children":50},"p",{},[51,58,60,66],{"type":39,"tag":52,"props":53,"children":55},"code",{"className":54},[],[56],{"type":45,"value":57},".shadow\u002F",{"type":45,"value":59}," mirrors the source tree. Each source file has a ",{"type":39,"tag":52,"props":61,"children":63},{"className":62},[],[64],{"type":45,"value":65},".md",{"type":45,"value":67}," shadow organized\nby symbol. Each symbol section contains discoveries — behavioral insights anchored\nto that code location.",{"type":39,"tag":69,"props":70,"children":72},"h2",{"id":71},"required-actions",[73],{"type":45,"value":74},"Required Actions",{"type":39,"tag":48,"props":76,"children":77},{},[78],{"type":39,"tag":79,"props":80,"children":81},"strong",{},[82,84,89],{"type":45,"value":83},"Every time you work on code in a repo with ",{"type":39,"tag":52,"props":85,"children":87},{"className":86},[],[88],{"type":45,"value":57},{"type":45,"value":90},":",{"type":39,"tag":92,"props":93,"children":94},"ol",{},[95,114,138,164,211,244,261],{"type":39,"tag":96,"props":97,"children":98},"li",{},[99,112],{"type":39,"tag":79,"props":100,"children":101},{},[102,104,110],{"type":45,"value":103},"Read ",{"type":39,"tag":52,"props":105,"children":107},{"className":106},[],[108],{"type":45,"value":109},"_prefs.md",{"type":45,"value":111}," first",{"type":45,"value":113}," — it contains project-wide conventions,\nuser preferences, and things the user explicitly wants to avoid.\nViolating a preference wastes the user's time.",{"type":39,"tag":96,"props":115,"children":116},{},[117,129,131,136],{"type":39,"tag":79,"props":118,"children":119},{},[120,121,127],{"type":45,"value":103},{"type":39,"tag":52,"props":122,"children":124},{"className":123},[],[125],{"type":45,"value":126},"_cross\u002F",{"type":45,"value":128}," discoveries",{"type":45,"value":130}," — these are the highest-value findings,\nspanning multiple files. List ",{"type":39,"tag":52,"props":132,"children":134},{"className":133},[],[135],{"type":45,"value":126},{"type":45,"value":137}," and read any files whose titles\nrelate to the area you're working in. Cross-cutting discoveries reveal\nhidden contracts, interaction bugs, and design patterns that per-file\nshadows alone cannot capture.",{"type":39,"tag":96,"props":139,"children":140},{},[141,154,156,162],{"type":39,"tag":79,"props":142,"children":143},{},[144,146,152],{"type":45,"value":145},"Check ",{"type":39,"tag":52,"props":147,"children":149},{"className":148},[],[150],{"type":45,"value":151},"_dreams\u002F",{"type":45,"value":153}," for experiment results",{"type":45,"value":155}," — ",{"type":39,"tag":52,"props":157,"children":159},{"className":158},[],[160],{"type":45,"value":161},"_dreams\u002F_index.md",{"type":45,"value":163}," lists\nautonomous exploration experiments. Read reports relevant to your task —\nthey contain verified bug analyses, attempted fixes, and architectural\ninsights. Dreams may contain knowledge not yet distilled into per-file\nshadows, so always check when investigating a bug or unfamiliar area.",{"type":39,"tag":96,"props":165,"children":166},{},[167,172,174,180,182,187,189,194,196,202,204,209],{"type":39,"tag":79,"props":168,"children":169},{},[170],{"type":45,"value":171},"Before editing any file",{"type":45,"value":173},": read its shadow (",{"type":39,"tag":52,"props":175,"children":177},{"className":176},[],[178],{"type":45,"value":179},".shadow\u002F\u003Cpath>.md",{"type":45,"value":181},"),\ncheck ",{"type":39,"tag":52,"props":183,"children":185},{"className":184},[],[186],{"type":45,"value":126},{"type":45,"value":188}," for cross-cutting discoveries about it, and apply\nwhat you learn. The shadow contains known bugs, edge cases, and\nimplicit contracts discovered by previous sessions.\n",{"type":39,"tag":79,"props":190,"children":191},{},[192],{"type":45,"value":193},"Note",{"type":45,"value":195},": ",{"type":39,"tag":52,"props":197,"children":199},{"className":198},[],[200],{"type":45,"value":201},"_index.md",{"type":45,"value":203}," discovery counts may be stale — always check\nper-file shadows and ",{"type":39,"tag":52,"props":205,"children":207},{"className":206},[],[208],{"type":45,"value":126},{"type":45,"value":210}," directly rather than relying solely on\nthe index summary.",{"type":39,"tag":96,"props":212,"children":213},{},[214,219,221,227,229,235,237,242],{"type":39,"tag":79,"props":215,"children":216},{},[217],{"type":45,"value":218},"When the user explains something about code",{"type":45,"value":220}," (gotcha, design intent,\nwarning, history): write a ",{"type":39,"tag":52,"props":222,"children":224},{"className":223},[],[225],{"type":45,"value":226},"source: user",{"type":45,"value":228}," discovery to the shadow\nimmediately. Do not ask where to put it — resolve the ",{"type":39,"tag":52,"props":230,"children":232},{"className":231},[],[233],{"type":45,"value":234},"file::symbol",{"type":45,"value":236},"\nanchor yourself by searching ",{"type":39,"tag":52,"props":238,"children":240},{"className":239},[],[241],{"type":45,"value":201},{"type":45,"value":243},", shadow files, and session\ncontext (current file, recent edits).",{"type":39,"tag":96,"props":245,"children":246},{},[247,252,254,259],{"type":39,"tag":79,"props":248,"children":249},{},[250],{"type":45,"value":251},"When the user states a preference or convention",{"type":45,"value":253}," (not tied to any\nspecific file): write it to ",{"type":39,"tag":52,"props":255,"children":257},{"className":256},[],[258],{"type":45,"value":109},{"type":45,"value":260}," immediately.",{"type":39,"tag":96,"props":262,"children":263},{},[264,269,271],{"type":39,"tag":79,"props":265,"children":266},{},[267],{"type":45,"value":268},"After code changes",{"type":45,"value":270},": run ",{"type":39,"tag":52,"props":272,"children":274},{"className":273},[],[275],{"type":45,"value":276},"\u002Fshadow-frog-update",{"type":39,"tag":69,"props":278,"children":280},{"id":279},"directory-layout",[281],{"type":45,"value":282},"Directory Layout",{"type":39,"tag":284,"props":285,"children":289},"pre",{"className":286,"code":288,"language":45},[287],"language-text",".shadow\u002F\n  .shadowignore      Gitignore-syntax file for excluding paths from the shadow\n  _index.md          File list with symbol counts and discovery counts\n  _prefs.md          Project-wide user preferences (not tied to any file\u002Fsymbol)\n  _cross\u002F            Cross-cutting discoveries (span multiple files)\n    \u003Cslug>.md        One file per cross-cutting discovery (descriptive kebab-case name)\n  _meta\u002F\n    state.json       Last commit, timestamps, counts\n  _dreams\u002F           Dream experiment archive (detailed reports + diffs)\n    _index.md        Table of all experiments with verdicts\n    \u003CYYYYMMDD-HHMMSSZ-slug>\u002F      One folder per experiment\n      report.md      Structured report with YAML frontmatter\n      patch.diff     Full implementation diff against base_commit\n  \u003Cmirrored tree>\u002F   Per-file shadows\n    file.py.md       Organized by symbol\n",[290],{"type":39,"tag":52,"props":291,"children":293},{"__ignoreMap":292},"",[294],{"type":45,"value":288},{"type":39,"tag":69,"props":296,"children":298},{"id":297},"reference-notation",[299],{"type":45,"value":300},"Reference Notation",{"type":39,"tag":48,"props":302,"children":303},{},[304,306],{"type":45,"value":305},"Canonical format: ",{"type":39,"tag":52,"props":307,"children":309},{"className":308},[],[310],{"type":45,"value":311},"file_path::symbol_name",{"type":39,"tag":48,"props":313,"children":314},{},[315,317,323,325,331,333,339],{"type":45,"value":316},"Examples: ",{"type":39,"tag":52,"props":318,"children":320},{"className":319},[],[321],{"type":45,"value":322},"src\u002Fauth.py::authenticate_user",{"type":45,"value":324},", ",{"type":39,"tag":52,"props":326,"children":328},{"className":327},[],[329],{"type":45,"value":330},"src\u002Fauth.py::UserAuth.validate",{"type":45,"value":332},",\n",{"type":39,"tag":52,"props":334,"children":336},{"className":335},[],[337],{"type":45,"value":338},"src\u002Fauth.py",{"type":45,"value":340}," (file-level, no symbol)",{"type":39,"tag":48,"props":342,"children":343},{},[344],{"type":45,"value":345},"The symbol name is the stable anchor.",{"type":39,"tag":69,"props":347,"children":349},{"id":348},"per-file-shadow-format",[350],{"type":45,"value":351},"Per-File Shadow Format",{"type":39,"tag":284,"props":353,"children":357},{"className":354,"code":355,"language":356,"meta":292,"style":292},"language-markdown shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","# Shadow: src\u002Fauth.py\n\n**Language**: Python | **Lines**: 142 | **Last modified**: 2025-01-15\n\n## File-Level\n\n- This module has no __all__ — all top-level names are public.\n  _(verified, source: exploration)_\n\n## `class UserAuth`\n\n### `UserAuth.validate`\n\n- Catches ALL exceptions and returns False — swallows\n  connection errors, making network failures look like invalid tokens.\n  _(verified, source: exploration)_\n\n## `authenticate_user`\n\n- Silently returns None on expired tokens. Callers must check.\n  _(verified, source: exploration, labels: [bug])_\n  Also involves: `src\u002Fmiddleware.py::require_auth`\n\n## Cross-References\n\n- [db-connection-lifecycle](..\u002F_cross\u002Fdb-connection-lifecycle.md)\n  (involves `src\u002Fdb\u002Fconnection.py::ConnectionPool`, `src\u002Fapi\u002Froutes.py::get_user`)\n","markdown",[358],{"type":39,"tag":52,"props":359,"children":360},{"__ignoreMap":292},[361,379,389,450,458,472,480,513,534,542,566,574,596,603,616,625,641,649,670,678,691,729,751,759,772,780,814],{"type":39,"tag":362,"props":363,"children":366},"span",{"class":364,"line":365},"line",1,[367,373],{"type":39,"tag":362,"props":368,"children":370},{"style":369},"--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF",[371],{"type":45,"value":372},"# ",{"type":39,"tag":362,"props":374,"children":376},{"style":375},"--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B",[377],{"type":45,"value":378},"Shadow: src\u002Fauth.py\n",{"type":39,"tag":362,"props":380,"children":382},{"class":364,"line":381},2,[383],{"type":39,"tag":362,"props":384,"children":386},{"emptyLinePlaceholder":385},true,[387],{"type":45,"value":388},"\n",{"type":39,"tag":362,"props":390,"children":391},{"class":364,"line":26},[392,398,404,408,414,418,423,427,432,436,441,445],{"type":39,"tag":362,"props":393,"children":395},{"style":394},"--shiki-light:#39ADB5;--shiki-light-font-weight:bold;--shiki-default:#89DDFF;--shiki-default-font-weight:bold;--shiki-dark:#89DDFF;--shiki-dark-font-weight:bold",[396],{"type":45,"value":397},"**",{"type":39,"tag":362,"props":399,"children":401},{"style":400},"--shiki-light:#E53935;--shiki-light-font-weight:bold;--shiki-default:#F07178;--shiki-default-font-weight:bold;--shiki-dark:#F07178;--shiki-dark-font-weight:bold",[402],{"type":45,"value":403},"Language",{"type":39,"tag":362,"props":405,"children":406},{"style":394},[407],{"type":45,"value":397},{"type":39,"tag":362,"props":409,"children":411},{"style":410},"--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8",[412],{"type":45,"value":413},": Python | ",{"type":39,"tag":362,"props":415,"children":416},{"style":394},[417],{"type":45,"value":397},{"type":39,"tag":362,"props":419,"children":420},{"style":400},[421],{"type":45,"value":422},"Lines",{"type":39,"tag":362,"props":424,"children":425},{"style":394},[426],{"type":45,"value":397},{"type":39,"tag":362,"props":428,"children":429},{"style":410},[430],{"type":45,"value":431},": 142 | ",{"type":39,"tag":362,"props":433,"children":434},{"style":394},[435],{"type":45,"value":397},{"type":39,"tag":362,"props":437,"children":438},{"style":400},[439],{"type":45,"value":440},"Last modified",{"type":39,"tag":362,"props":442,"children":443},{"style":394},[444],{"type":45,"value":397},{"type":39,"tag":362,"props":446,"children":447},{"style":410},[448],{"type":45,"value":449},": 2025-01-15\n",{"type":39,"tag":362,"props":451,"children":453},{"class":364,"line":452},4,[454],{"type":39,"tag":362,"props":455,"children":456},{"emptyLinePlaceholder":385},[457],{"type":45,"value":388},{"type":39,"tag":362,"props":459,"children":461},{"class":364,"line":460},5,[462,467],{"type":39,"tag":362,"props":463,"children":464},{"style":369},[465],{"type":45,"value":466},"## ",{"type":39,"tag":362,"props":468,"children":469},{"style":375},[470],{"type":45,"value":471},"File-Level\n",{"type":39,"tag":362,"props":473,"children":475},{"class":364,"line":474},6,[476],{"type":39,"tag":362,"props":477,"children":478},{"emptyLinePlaceholder":385},[479],{"type":45,"value":388},{"type":39,"tag":362,"props":481,"children":483},{"class":364,"line":482},7,[484,489,494,499,504,508],{"type":39,"tag":362,"props":485,"children":486},{"style":369},[487],{"type":45,"value":488},"-",{"type":39,"tag":362,"props":490,"children":491},{"style":410},[492],{"type":45,"value":493}," This module has no ",{"type":39,"tag":362,"props":495,"children":496},{"style":394},[497],{"type":45,"value":498},"__",{"type":39,"tag":362,"props":500,"children":501},{"style":400},[502],{"type":45,"value":503},"all",{"type":39,"tag":362,"props":505,"children":506},{"style":394},[507],{"type":45,"value":498},{"type":39,"tag":362,"props":509,"children":510},{"style":410},[511],{"type":45,"value":512}," — all top-level names are public.\n",{"type":39,"tag":362,"props":514,"children":516},{"class":364,"line":515},8,[517,523,529],{"type":39,"tag":362,"props":518,"children":520},{"style":519},"--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#89DDFF;--shiki-default-font-style:italic;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic",[521],{"type":45,"value":522},"  _",{"type":39,"tag":362,"props":524,"children":526},{"style":525},"--shiki-light:#E53935;--shiki-light-font-style:italic;--shiki-default:#F07178;--shiki-default-font-style:italic;--shiki-dark:#F07178;--shiki-dark-font-style:italic",[527],{"type":45,"value":528},"(verified, source: exploration)",{"type":39,"tag":362,"props":530,"children":531},{"style":519},[532],{"type":45,"value":533},"_\n",{"type":39,"tag":362,"props":535,"children":537},{"class":364,"line":536},9,[538],{"type":39,"tag":362,"props":539,"children":540},{"emptyLinePlaceholder":385},[541],{"type":45,"value":388},{"type":39,"tag":362,"props":543,"children":545},{"class":364,"line":544},10,[546,550,555,561],{"type":39,"tag":362,"props":547,"children":548},{"style":369},[549],{"type":45,"value":466},{"type":39,"tag":362,"props":551,"children":552},{"style":369},[553],{"type":45,"value":554},"`",{"type":39,"tag":362,"props":556,"children":558},{"style":557},"--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D",[559],{"type":45,"value":560},"class UserAuth",{"type":39,"tag":362,"props":562,"children":563},{"style":369},[564],{"type":45,"value":565},"`\n",{"type":39,"tag":362,"props":567,"children":569},{"class":364,"line":568},11,[570],{"type":39,"tag":362,"props":571,"children":572},{"emptyLinePlaceholder":385},[573],{"type":45,"value":388},{"type":39,"tag":362,"props":575,"children":577},{"class":364,"line":576},12,[578,583,587,592],{"type":39,"tag":362,"props":579,"children":580},{"style":369},[581],{"type":45,"value":582},"### ",{"type":39,"tag":362,"props":584,"children":585},{"style":369},[586],{"type":45,"value":554},{"type":39,"tag":362,"props":588,"children":589},{"style":557},[590],{"type":45,"value":591},"UserAuth.validate",{"type":39,"tag":362,"props":593,"children":594},{"style":369},[595],{"type":45,"value":565},{"type":39,"tag":362,"props":597,"children":598},{"class":364,"line":22},[599],{"type":39,"tag":362,"props":600,"children":601},{"emptyLinePlaceholder":385},[602],{"type":45,"value":388},{"type":39,"tag":362,"props":604,"children":606},{"class":364,"line":605},14,[607,611],{"type":39,"tag":362,"props":608,"children":609},{"style":369},[610],{"type":45,"value":488},{"type":39,"tag":362,"props":612,"children":613},{"style":410},[614],{"type":45,"value":615}," Catches ALL exceptions and returns False — swallows\n",{"type":39,"tag":362,"props":617,"children":619},{"class":364,"line":618},15,[620],{"type":39,"tag":362,"props":621,"children":622},{"style":410},[623],{"type":45,"value":624},"  connection errors, making network failures look like invalid tokens.\n",{"type":39,"tag":362,"props":626,"children":628},{"class":364,"line":627},16,[629,633,637],{"type":39,"tag":362,"props":630,"children":631},{"style":519},[632],{"type":45,"value":522},{"type":39,"tag":362,"props":634,"children":635},{"style":525},[636],{"type":45,"value":528},{"type":39,"tag":362,"props":638,"children":639},{"style":519},[640],{"type":45,"value":533},{"type":39,"tag":362,"props":642,"children":644},{"class":364,"line":643},17,[645],{"type":39,"tag":362,"props":646,"children":647},{"emptyLinePlaceholder":385},[648],{"type":45,"value":388},{"type":39,"tag":362,"props":650,"children":652},{"class":364,"line":651},18,[653,657,661,666],{"type":39,"tag":362,"props":654,"children":655},{"style":369},[656],{"type":45,"value":466},{"type":39,"tag":362,"props":658,"children":659},{"style":369},[660],{"type":45,"value":554},{"type":39,"tag":362,"props":662,"children":663},{"style":557},[664],{"type":45,"value":665},"authenticate_user",{"type":39,"tag":362,"props":667,"children":668},{"style":369},[669],{"type":45,"value":565},{"type":39,"tag":362,"props":671,"children":673},{"class":364,"line":672},19,[674],{"type":39,"tag":362,"props":675,"children":676},{"emptyLinePlaceholder":385},[677],{"type":45,"value":388},{"type":39,"tag":362,"props":679,"children":681},{"class":364,"line":680},20,[682,686],{"type":39,"tag":362,"props":683,"children":684},{"style":369},[685],{"type":45,"value":488},{"type":39,"tag":362,"props":687,"children":688},{"style":410},[689],{"type":45,"value":690}," Silently returns None on expired tokens. Callers must check.\n",{"type":39,"tag":362,"props":692,"children":694},{"class":364,"line":693},21,[695,699,704,709,715,720,725],{"type":39,"tag":362,"props":696,"children":697},{"style":519},[698],{"type":45,"value":522},{"type":39,"tag":362,"props":700,"children":701},{"style":525},[702],{"type":45,"value":703},"(verified, source: exploration, labels: ",{"type":39,"tag":362,"props":705,"children":706},{"style":519},[707],{"type":45,"value":708},"[",{"type":39,"tag":362,"props":710,"children":712},{"style":711},"--shiki-light:#91B859;--shiki-light-font-style:italic;--shiki-default:#C3E88D;--shiki-default-font-style:italic;--shiki-dark:#C3E88D;--shiki-dark-font-style:italic",[713],{"type":45,"value":714},"bug",{"type":39,"tag":362,"props":716,"children":717},{"style":519},[718],{"type":45,"value":719},"]",{"type":39,"tag":362,"props":721,"children":722},{"style":525},[723],{"type":45,"value":724},")",{"type":39,"tag":362,"props":726,"children":727},{"style":519},[728],{"type":45,"value":533},{"type":39,"tag":362,"props":730,"children":732},{"class":364,"line":731},22,[733,738,742,747],{"type":39,"tag":362,"props":734,"children":735},{"style":410},[736],{"type":45,"value":737},"  Also involves: ",{"type":39,"tag":362,"props":739,"children":740},{"style":369},[741],{"type":45,"value":554},{"type":39,"tag":362,"props":743,"children":744},{"style":557},[745],{"type":45,"value":746},"src\u002Fmiddleware.py::require_auth",{"type":39,"tag":362,"props":748,"children":749},{"style":369},[750],{"type":45,"value":565},{"type":39,"tag":362,"props":752,"children":754},{"class":364,"line":753},23,[755],{"type":39,"tag":362,"props":756,"children":757},{"emptyLinePlaceholder":385},[758],{"type":45,"value":388},{"type":39,"tag":362,"props":760,"children":762},{"class":364,"line":761},24,[763,767],{"type":39,"tag":362,"props":764,"children":765},{"style":369},[766],{"type":45,"value":466},{"type":39,"tag":362,"props":768,"children":769},{"style":375},[770],{"type":45,"value":771},"Cross-References\n",{"type":39,"tag":362,"props":773,"children":775},{"class":364,"line":774},25,[776],{"type":39,"tag":362,"props":777,"children":778},{"emptyLinePlaceholder":385},[779],{"type":45,"value":388},{"type":39,"tag":362,"props":781,"children":783},{"class":364,"line":782},26,[784,788,793,798,803,809],{"type":39,"tag":362,"props":785,"children":786},{"style":369},[787],{"type":45,"value":488},{"type":39,"tag":362,"props":789,"children":790},{"style":369},[791],{"type":45,"value":792}," [",{"type":39,"tag":362,"props":794,"children":795},{"style":557},[796],{"type":45,"value":797},"db-connection-lifecycle",{"type":39,"tag":362,"props":799,"children":800},{"style":369},[801],{"type":45,"value":802},"](",{"type":39,"tag":362,"props":804,"children":806},{"style":805},"--shiki-light:#E53935;--shiki-light-text-decoration:underline;--shiki-default:#F07178;--shiki-default-text-decoration:underline;--shiki-dark:#F07178;--shiki-dark-text-decoration:underline",[807],{"type":45,"value":808},"..\u002F_cross\u002Fdb-connection-lifecycle.md",{"type":39,"tag":362,"props":810,"children":811},{"style":369},[812],{"type":45,"value":813},")\n",{"type":39,"tag":362,"props":815,"children":817},{"class":364,"line":816},27,[818,823,827,832,836,840,844,849,853],{"type":39,"tag":362,"props":819,"children":820},{"style":410},[821],{"type":45,"value":822},"  (involves ",{"type":39,"tag":362,"props":824,"children":825},{"style":369},[826],{"type":45,"value":554},{"type":39,"tag":362,"props":828,"children":829},{"style":557},[830],{"type":45,"value":831},"src\u002Fdb\u002Fconnection.py::ConnectionPool",{"type":39,"tag":362,"props":833,"children":834},{"style":369},[835],{"type":45,"value":554},{"type":39,"tag":362,"props":837,"children":838},{"style":410},[839],{"type":45,"value":324},{"type":39,"tag":362,"props":841,"children":842},{"style":369},[843],{"type":45,"value":554},{"type":39,"tag":362,"props":845,"children":846},{"style":557},[847],{"type":45,"value":848},"src\u002Fapi\u002Froutes.py::get_user",{"type":39,"tag":362,"props":850,"children":851},{"style":369},[852],{"type":45,"value":554},{"type":39,"tag":362,"props":854,"children":855},{"style":410},[856],{"type":45,"value":813},{"type":39,"tag":48,"props":858,"children":859},{},[860,862,867],{"type":45,"value":861},"Heading format (",{"type":39,"tag":79,"props":863,"children":864},{},[865],{"type":45,"value":866},"hard rule — parsers depend on this",{"type":45,"value":868},"):",{"type":39,"tag":870,"props":871,"children":872},"ul",{},[873,886,898],{"type":39,"tag":96,"props":874,"children":875},{},[876,878,884],{"type":45,"value":877},"Top-level symbols (classes, functions, constants): ",{"type":39,"tag":52,"props":879,"children":881},{"className":880},[],[882],{"type":45,"value":883},"##",{"type":45,"value":885}," heading with symbol in backticks",{"type":39,"tag":96,"props":887,"children":888},{},[889,891,897],{"type":45,"value":890},"Nested symbols (methods): ",{"type":39,"tag":52,"props":892,"children":894},{"className":893},[],[895],{"type":45,"value":896},"###",{"type":45,"value":885},{"type":39,"tag":96,"props":899,"children":900},{},[901,907],{"type":39,"tag":52,"props":902,"children":904},{"className":903},[],[905],{"type":45,"value":906},"## Cross-References",{"type":45,"value":908}," — always last section",{"type":39,"tag":48,"props":910,"children":911},{},[912,914,920],{"type":45,"value":913},"The viewer parser only matches the backtick form. A heading written as\n",{"type":39,"tag":52,"props":915,"children":917},{"className":916},[],[918],{"type":45,"value":919},"### UserAuth.validate",{"type":45,"value":921}," (no backticks) will have its discoveries\nsilently dropped from search\u002Ftop output. Always wrap the symbol in\nbackticks, including for nested symbols.",{"type":39,"tag":48,"props":923,"children":924},{},[925],{"type":45,"value":926},"Examples:",{"type":39,"tag":284,"props":928,"children":931},{"className":929,"code":930,"language":45},[287],"## `authenticate_user`\n## `class UserAuth`\n### `UserAuth.validate`\n",[932],{"type":39,"tag":52,"props":933,"children":934},{"__ignoreMap":292},[935],{"type":45,"value":930},{"type":39,"tag":69,"props":937,"children":939},{"id":938},"cross-cutting-file-format-_crossslugmd",[940,942,948],{"type":45,"value":941},"Cross-Cutting File Format (",{"type":39,"tag":52,"props":943,"children":945},{"className":944},[],[946],{"type":45,"value":947},"_cross\u002F\u003Cslug>.md",{"type":45,"value":724},{"type":39,"tag":284,"props":950,"children":952},{"className":354,"code":951,"language":356,"meta":292,"style":292},"# Database connection lifecycle\n\n**Category**: pattern\n**Refs**:\n- `src\u002Fdb\u002Fconnection.py::ConnectionPool.get`\n- `src\u002Fauth.py::authenticate_user`\n- `src\u002Fapi\u002Froutes.py::get_user`\n\n**Discovery**: All database access goes through a connection pool that\nsilently reconnects on failure. First request after DB restart is slow (~2s).\n\n_(verified, source: exploration)_\n",[953],{"type":39,"tag":52,"props":954,"children":955},{"__ignoreMap":292},[956,968,975,996,1017,1038,1057,1076,1083,1104,1112,1119],{"type":39,"tag":362,"props":957,"children":958},{"class":364,"line":365},[959,963],{"type":39,"tag":362,"props":960,"children":961},{"style":369},[962],{"type":45,"value":372},{"type":39,"tag":362,"props":964,"children":965},{"style":375},[966],{"type":45,"value":967},"Database connection lifecycle\n",{"type":39,"tag":362,"props":969,"children":970},{"class":364,"line":381},[971],{"type":39,"tag":362,"props":972,"children":973},{"emptyLinePlaceholder":385},[974],{"type":45,"value":388},{"type":39,"tag":362,"props":976,"children":977},{"class":364,"line":26},[978,982,987,991],{"type":39,"tag":362,"props":979,"children":980},{"style":394},[981],{"type":45,"value":397},{"type":39,"tag":362,"props":983,"children":984},{"style":400},[985],{"type":45,"value":986},"Category",{"type":39,"tag":362,"props":988,"children":989},{"style":394},[990],{"type":45,"value":397},{"type":39,"tag":362,"props":992,"children":993},{"style":410},[994],{"type":45,"value":995},": pattern\n",{"type":39,"tag":362,"props":997,"children":998},{"class":364,"line":452},[999,1003,1008,1012],{"type":39,"tag":362,"props":1000,"children":1001},{"style":394},[1002],{"type":45,"value":397},{"type":39,"tag":362,"props":1004,"children":1005},{"style":400},[1006],{"type":45,"value":1007},"Refs",{"type":39,"tag":362,"props":1009,"children":1010},{"style":394},[1011],{"type":45,"value":397},{"type":39,"tag":362,"props":1013,"children":1014},{"style":410},[1015],{"type":45,"value":1016},":\n",{"type":39,"tag":362,"props":1018,"children":1019},{"class":364,"line":460},[1020,1024,1029,1034],{"type":39,"tag":362,"props":1021,"children":1022},{"style":369},[1023],{"type":45,"value":488},{"type":39,"tag":362,"props":1025,"children":1026},{"style":369},[1027],{"type":45,"value":1028}," `",{"type":39,"tag":362,"props":1030,"children":1031},{"style":557},[1032],{"type":45,"value":1033},"src\u002Fdb\u002Fconnection.py::ConnectionPool.get",{"type":39,"tag":362,"props":1035,"children":1036},{"style":369},[1037],{"type":45,"value":565},{"type":39,"tag":362,"props":1039,"children":1040},{"class":364,"line":474},[1041,1045,1049,1053],{"type":39,"tag":362,"props":1042,"children":1043},{"style":369},[1044],{"type":45,"value":488},{"type":39,"tag":362,"props":1046,"children":1047},{"style":369},[1048],{"type":45,"value":1028},{"type":39,"tag":362,"props":1050,"children":1051},{"style":557},[1052],{"type":45,"value":322},{"type":39,"tag":362,"props":1054,"children":1055},{"style":369},[1056],{"type":45,"value":565},{"type":39,"tag":362,"props":1058,"children":1059},{"class":364,"line":482},[1060,1064,1068,1072],{"type":39,"tag":362,"props":1061,"children":1062},{"style":369},[1063],{"type":45,"value":488},{"type":39,"tag":362,"props":1065,"children":1066},{"style":369},[1067],{"type":45,"value":1028},{"type":39,"tag":362,"props":1069,"children":1070},{"style":557},[1071],{"type":45,"value":848},{"type":39,"tag":362,"props":1073,"children":1074},{"style":369},[1075],{"type":45,"value":565},{"type":39,"tag":362,"props":1077,"children":1078},{"class":364,"line":515},[1079],{"type":39,"tag":362,"props":1080,"children":1081},{"emptyLinePlaceholder":385},[1082],{"type":45,"value":388},{"type":39,"tag":362,"props":1084,"children":1085},{"class":364,"line":536},[1086,1090,1095,1099],{"type":39,"tag":362,"props":1087,"children":1088},{"style":394},[1089],{"type":45,"value":397},{"type":39,"tag":362,"props":1091,"children":1092},{"style":400},[1093],{"type":45,"value":1094},"Discovery",{"type":39,"tag":362,"props":1096,"children":1097},{"style":394},[1098],{"type":45,"value":397},{"type":39,"tag":362,"props":1100,"children":1101},{"style":410},[1102],{"type":45,"value":1103},": All database access goes through a connection pool that\n",{"type":39,"tag":362,"props":1105,"children":1106},{"class":364,"line":544},[1107],{"type":39,"tag":362,"props":1108,"children":1109},{"style":410},[1110],{"type":45,"value":1111},"silently reconnects on failure. First request after DB restart is slow (~2s).\n",{"type":39,"tag":362,"props":1113,"children":1114},{"class":364,"line":568},[1115],{"type":39,"tag":362,"props":1116,"children":1117},{"emptyLinePlaceholder":385},[1118],{"type":45,"value":388},{"type":39,"tag":362,"props":1120,"children":1121},{"class":364,"line":576},[1122,1127,1131],{"type":39,"tag":362,"props":1123,"children":1124},{"style":519},[1125],{"type":45,"value":1126},"_",{"type":39,"tag":362,"props":1128,"children":1129},{"style":525},[1130],{"type":45,"value":528},{"type":39,"tag":362,"props":1132,"children":1133},{"style":519},[1134],{"type":45,"value":533},{"type":39,"tag":69,"props":1136,"children":1138},{"id":1137},"preferences-file-_prefsmd",[1139,1141,1146],{"type":45,"value":1140},"Preferences File (",{"type":39,"tag":52,"props":1142,"children":1144},{"className":1143},[],[1145],{"type":45,"value":109},{"type":45,"value":724},{"type":39,"tag":48,"props":1148,"children":1149},{},[1150],{"type":45,"value":1151},"Project-wide user preferences and conventions that are not tied to any\nspecific file or symbol. These guide all agent work across the codebase.",{"type":39,"tag":284,"props":1153,"children":1155},{"className":354,"code":1154,"language":356,"meta":292,"style":292},"# Preferences\n\n- No backward compatibility — only keep the latest code, no shims or aliases.\n  _(source: user)_\n\n- Use snake_case for all Python function and variable names.\n  _(source: user)_\n\n- Prefer small, focused PRs over large sweeping changes.\n  _(source: interaction)_\n",[1156],{"type":39,"tag":52,"props":1157,"children":1158},{"__ignoreMap":292},[1159,1171,1178,1190,1206,1213,1225,1240,1247,1259],{"type":39,"tag":362,"props":1160,"children":1161},{"class":364,"line":365},[1162,1166],{"type":39,"tag":362,"props":1163,"children":1164},{"style":369},[1165],{"type":45,"value":372},{"type":39,"tag":362,"props":1167,"children":1168},{"style":375},[1169],{"type":45,"value":1170},"Preferences\n",{"type":39,"tag":362,"props":1172,"children":1173},{"class":364,"line":381},[1174],{"type":39,"tag":362,"props":1175,"children":1176},{"emptyLinePlaceholder":385},[1177],{"type":45,"value":388},{"type":39,"tag":362,"props":1179,"children":1180},{"class":364,"line":26},[1181,1185],{"type":39,"tag":362,"props":1182,"children":1183},{"style":369},[1184],{"type":45,"value":488},{"type":39,"tag":362,"props":1186,"children":1187},{"style":410},[1188],{"type":45,"value":1189}," No backward compatibility — only keep the latest code, no shims or aliases.\n",{"type":39,"tag":362,"props":1191,"children":1192},{"class":364,"line":452},[1193,1197,1202],{"type":39,"tag":362,"props":1194,"children":1195},{"style":519},[1196],{"type":45,"value":522},{"type":39,"tag":362,"props":1198,"children":1199},{"style":525},[1200],{"type":45,"value":1201},"(source: user)",{"type":39,"tag":362,"props":1203,"children":1204},{"style":519},[1205],{"type":45,"value":533},{"type":39,"tag":362,"props":1207,"children":1208},{"class":364,"line":460},[1209],{"type":39,"tag":362,"props":1210,"children":1211},{"emptyLinePlaceholder":385},[1212],{"type":45,"value":388},{"type":39,"tag":362,"props":1214,"children":1215},{"class":364,"line":474},[1216,1220],{"type":39,"tag":362,"props":1217,"children":1218},{"style":369},[1219],{"type":45,"value":488},{"type":39,"tag":362,"props":1221,"children":1222},{"style":410},[1223],{"type":45,"value":1224}," Use snake_case for all Python function and variable names.\n",{"type":39,"tag":362,"props":1226,"children":1227},{"class":364,"line":482},[1228,1232,1236],{"type":39,"tag":362,"props":1229,"children":1230},{"style":519},[1231],{"type":45,"value":522},{"type":39,"tag":362,"props":1233,"children":1234},{"style":525},[1235],{"type":45,"value":1201},{"type":39,"tag":362,"props":1237,"children":1238},{"style":519},[1239],{"type":45,"value":533},{"type":39,"tag":362,"props":1241,"children":1242},{"class":364,"line":515},[1243],{"type":39,"tag":362,"props":1244,"children":1245},{"emptyLinePlaceholder":385},[1246],{"type":45,"value":388},{"type":39,"tag":362,"props":1248,"children":1249},{"class":364,"line":536},[1250,1254],{"type":39,"tag":362,"props":1251,"children":1252},{"style":369},[1253],{"type":45,"value":488},{"type":39,"tag":362,"props":1255,"children":1256},{"style":410},[1257],{"type":45,"value":1258}," Prefer small, focused PRs over large sweeping changes.\n",{"type":39,"tag":362,"props":1260,"children":1261},{"class":364,"line":544},[1262,1266,1271],{"type":39,"tag":362,"props":1263,"children":1264},{"style":519},[1265],{"type":45,"value":522},{"type":39,"tag":362,"props":1267,"children":1268},{"style":525},[1269],{"type":45,"value":1270},"(source: interaction)",{"type":39,"tag":362,"props":1272,"children":1273},{"style":519},[1274],{"type":45,"value":533},{"type":39,"tag":48,"props":1276,"children":1277},{},[1278],{"type":45,"value":1279},"Format:",{"type":39,"tag":284,"props":1281,"children":1284},{"className":1282,"code":1283,"language":45},[287],"- \u003Cpreference or convention>\n  _(source: \u003Cuser|interaction>)_\n",[1285],{"type":39,"tag":52,"props":1286,"children":1287},{"__ignoreMap":292},[1288],{"type":45,"value":1283},{"type":39,"tag":48,"props":1290,"children":1291},{},[1292,1294,1299,1301,1307],{"type":45,"value":1293},"Preferences are always trusted (same rank as ",{"type":39,"tag":52,"props":1295,"children":1297},{"className":1296},[],[1298],{"type":45,"value":226},{"type":45,"value":1300},"). They don't\nneed ",{"type":39,"tag":52,"props":1302,"children":1304},{"className":1303},[],[1305],{"type":45,"value":1306},"verified\u002Funcertain\u002Frefuted",{"type":45,"value":1308}," — if the user said it, it's a directive.",{"type":39,"tag":48,"props":1310,"children":1311},{},[1312,1314,1319,1321,1326],{"type":45,"value":1313},"When to write to ",{"type":39,"tag":52,"props":1315,"children":1317},{"className":1316},[],[1318],{"type":45,"value":109},{"type":45,"value":1320}," vs per-file shadow vs ",{"type":39,"tag":52,"props":1322,"children":1324},{"className":1323},[],[1325],{"type":45,"value":126},{"type":45,"value":90},{"type":39,"tag":870,"props":1328,"children":1329},{},[1330,1340,1345],{"type":39,"tag":96,"props":1331,"children":1332},{},[1333,1335],{"type":45,"value":1334},"Applies to the whole repo, no specific file → ",{"type":39,"tag":52,"props":1336,"children":1338},{"className":1337},[],[1339],{"type":45,"value":109},{"type":39,"tag":96,"props":1341,"children":1342},{},[1343],{"type":45,"value":1344},"Applies to a specific file or symbol → per-file shadow",{"type":39,"tag":96,"props":1346,"children":1347},{},[1348,1350],{"type":45,"value":1349},"Applies to 3+ specific files → ",{"type":39,"tag":52,"props":1351,"children":1353},{"className":1352},[],[1354],{"type":45,"value":947},{"type":39,"tag":69,"props":1356,"children":1358},{"id":1357},"discovery-format",[1359],{"type":45,"value":1360},"Discovery Format",{"type":39,"tag":48,"props":1362,"children":1363},{},[1364,1366,1371],{"type":45,"value":1365},"Per-file discoveries (no IDs — anchored by their ",{"type":39,"tag":52,"props":1367,"children":1369},{"className":1368},[],[1370],{"type":45,"value":234},{"type":45,"value":1372}," heading):",{"type":39,"tag":284,"props":1374,"children":1377},{"className":1375,"code":1376,"language":45},[287],"- \u003Cbehavioral statement>\n  _(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>)_\n  Also involves: `file::symbol`, `file::symbol`\n",[1378],{"type":39,"tag":52,"props":1379,"children":1380},{"__ignoreMap":292},[1381],{"type":45,"value":1376},{"type":39,"tag":48,"props":1383,"children":1384},{},[1385],{"type":45,"value":1386},"With labels (optional — only when the discovery is actionable):",{"type":39,"tag":284,"props":1388,"children":1391},{"className":1389,"code":1390,"language":45},[287],"- \u003Cbehavioral statement>\n  _(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>, labels: [bug, security])_\n  Also involves: `file::symbol`\n",[1392],{"type":39,"tag":52,"props":1393,"children":1394},{"__ignoreMap":292},[1395],{"type":45,"value":1390},{"type":39,"tag":48,"props":1397,"children":1398},{},[1399],{"type":45,"value":1400},"With dream report link (optional — only for experiment-derived discoveries):",{"type":39,"tag":284,"props":1402,"children":1405},{"className":1403,"code":1404,"language":45},[287],"- \u003Cbehavioral statement>\n  _(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>)_\n  Dream report: `_dreams\u002F\u003Cdream-id>\u002F`\n",[1406],{"type":39,"tag":52,"props":1407,"children":1408},{"__ignoreMap":292},[1409],{"type":45,"value":1404},{"type":39,"tag":48,"props":1411,"children":1412},{},[1413,1415,1420],{"type":45,"value":1414},"Cross-cutting discoveries (one per ",{"type":39,"tag":52,"props":1416,"children":1418},{"className":1417},[],[1419],{"type":45,"value":947},{"type":45,"value":1421}," file):",{"type":39,"tag":284,"props":1423,"children":1426},{"className":1424,"code":1425,"language":45},[287],"# \u003CTitle>\n\n**Category**: \u003Ccategory>\n**Refs**:\n- `file::symbol`\n\n**Discovery**: \u003Cbehavioral statement>\n\n_(\u003Cverified|uncertain|refuted>, source: \u003Cexploration|user|interaction>)_\n",[1427],{"type":39,"tag":52,"props":1428,"children":1429},{"__ignoreMap":292},[1430],{"type":45,"value":1425},{"type":39,"tag":48,"props":1432,"children":1433},{},[1434,1436],{"type":45,"value":1435},"Slug naming: use descriptive kebab-case derived from the title.\nExample: title \"Database connection lifecycle\" → filename ",{"type":39,"tag":52,"props":1437,"children":1439},{"className":1438},[],[1440],{"type":45,"value":1441},"db-connection-lifecycle.md",{"type":39,"tag":1443,"props":1444,"children":1446},"h3",{"id":1445},"labels",[1447],{"type":45,"value":1448},"Labels",{"type":39,"tag":48,"props":1450,"children":1451},{},[1452],{"type":45,"value":1453},"Labels mark actionable discoveries so agents can quickly scan for specific\ntypes. Most discoveries are just knowledge — labels are only for findings\nthat call for action.",{"type":39,"tag":1455,"props":1456,"children":1457},"table",{},[1458,1477],{"type":39,"tag":1459,"props":1460,"children":1461},"thead",{},[1462],{"type":39,"tag":1463,"props":1464,"children":1465},"tr",{},[1466,1472],{"type":39,"tag":1467,"props":1468,"children":1469},"th",{},[1470],{"type":45,"value":1471},"Label",{"type":39,"tag":1467,"props":1473,"children":1474},{},[1475],{"type":45,"value":1476},"Use when",{"type":39,"tag":1478,"props":1479,"children":1480},"tbody",{},[1481,1498,1515,1532,1549],{"type":39,"tag":1463,"props":1482,"children":1483},{},[1484,1493],{"type":39,"tag":1485,"props":1486,"children":1487},"td",{},[1488],{"type":39,"tag":52,"props":1489,"children":1491},{"className":1490},[],[1492],{"type":45,"value":714},{"type":39,"tag":1485,"props":1494,"children":1495},{},[1496],{"type":45,"value":1497},"A defect that should be fixed",{"type":39,"tag":1463,"props":1499,"children":1500},{},[1501,1510],{"type":39,"tag":1485,"props":1502,"children":1503},{},[1504],{"type":39,"tag":52,"props":1505,"children":1507},{"className":1506},[],[1508],{"type":45,"value":1509},"performance",{"type":39,"tag":1485,"props":1511,"children":1512},{},[1513],{"type":45,"value":1514},"A bottleneck or inefficiency",{"type":39,"tag":1463,"props":1516,"children":1517},{},[1518,1527],{"type":39,"tag":1485,"props":1519,"children":1520},{},[1521],{"type":39,"tag":52,"props":1522,"children":1524},{"className":1523},[],[1525],{"type":45,"value":1526},"security",{"type":39,"tag":1485,"props":1528,"children":1529},{},[1530],{"type":45,"value":1531},"A vulnerability or unsafe pattern",{"type":39,"tag":1463,"props":1533,"children":1534},{},[1535,1544],{"type":39,"tag":1485,"props":1536,"children":1537},{},[1538],{"type":39,"tag":52,"props":1539,"children":1541},{"className":1540},[],[1542],{"type":45,"value":1543},"feature-gap",{"type":39,"tag":1485,"props":1545,"children":1546},{},[1547],{"type":45,"value":1548},"Missing functionality or improvement opportunity",{"type":39,"tag":1463,"props":1550,"children":1551},{},[1552,1561],{"type":39,"tag":1485,"props":1553,"children":1554},{},[1555],{"type":39,"tag":52,"props":1556,"children":1558},{"className":1557},[],[1559],{"type":45,"value":1560},"tech-debt",{"type":39,"tag":1485,"props":1562,"children":1563},{},[1564],{"type":45,"value":1565},"Code smell, duplication, refactoring opportunity",{"type":39,"tag":48,"props":1567,"children":1568},{},[1569,1571,1577],{"type":45,"value":1570},"A discovery can have multiple labels: ",{"type":39,"tag":52,"props":1572,"children":1574},{"className":1573},[],[1575],{"type":45,"value":1576},"labels: [bug, security]",{"type":45,"value":1578},".\nOmit labels entirely for pure observational knowledge.",{"type":39,"tag":48,"props":1580,"children":1581},{},[1582],{"type":45,"value":1583},"Labels go in the metadata line:",{"type":39,"tag":284,"props":1585,"children":1588},{"className":1586,"code":1587,"language":45},[287],"_(verified, source: exploration, labels: [bug])_\n",[1589],{"type":39,"tag":52,"props":1590,"children":1591},{"__ignoreMap":292},[1592],{"type":45,"value":1587},{"type":39,"tag":48,"props":1594,"children":1595},{},[1596],{"type":45,"value":1597},"Cross-cutting discoveries can also have labels — add them to the metadata line.",{"type":39,"tag":1443,"props":1599,"children":1601},{"id":1600},"fields",[1602],{"type":45,"value":1603},"Fields",{"type":39,"tag":870,"props":1605,"children":1606},{},[1607,1618,1629,1639,1650,1661,1678,1697],{"type":39,"tag":96,"props":1608,"children":1609},{},[1610,1616],{"type":39,"tag":52,"props":1611,"children":1613},{"className":1612},[],[1614],{"type":45,"value":1615},"verified|uncertain|refuted",{"type":45,"value":1617}," — verification status",{"type":39,"tag":96,"props":1619,"children":1620},{},[1621,1627],{"type":39,"tag":52,"props":1622,"children":1624},{"className":1623},[],[1625],{"type":45,"value":1626},"source: exploration",{"type":45,"value":1628}," — agent discovered via code analysis",{"type":39,"tag":96,"props":1630,"children":1631},{},[1632,1637],{"type":39,"tag":52,"props":1633,"children":1635},{"className":1634},[],[1636],{"type":45,"value":226},{"type":45,"value":1638}," — human stated it in conversation",{"type":39,"tag":96,"props":1640,"children":1641},{},[1642,1648],{"type":39,"tag":52,"props":1643,"children":1645},{"className":1644},[],[1646],{"type":45,"value":1647},"source: interaction",{"type":45,"value":1649}," — emerged from collaborative work (debugging, refactoring)",{"type":39,"tag":96,"props":1651,"children":1652},{},[1653,1659],{"type":39,"tag":52,"props":1654,"children":1656},{"className":1655},[],[1657],{"type":45,"value":1658},"labels: [...]",{"type":45,"value":1660}," — optional, actionable labels (see table above)",{"type":39,"tag":96,"props":1662,"children":1663},{},[1664,1670,1671,1676],{"type":39,"tag":52,"props":1665,"children":1667},{"className":1666},[],[1668],{"type":45,"value":1669},"Also involves:",{"type":45,"value":155},{"type":39,"tag":52,"props":1672,"children":1674},{"className":1673},[],[1675],{"type":45,"value":234},{"type":45,"value":1677}," refs to other code locations (required if discovery touches other files)",{"type":39,"tag":96,"props":1679,"children":1680},{},[1681,1687,1689,1695],{"type":39,"tag":52,"props":1682,"children":1684},{"className":1683},[],[1685],{"type":45,"value":1686},"Dream report:",{"type":45,"value":1688}," — optional, ",{"type":39,"tag":52,"props":1690,"children":1692},{"className":1691},[],[1693],{"type":45,"value":1694},"_dreams\u002F\u003Cdream-id>\u002F",{"type":45,"value":1696}," link for experiment-derived discoveries",{"type":39,"tag":96,"props":1698,"children":1699},{},[1700,1705],{"type":39,"tag":52,"props":1701,"children":1703},{"className":1702},[],[1704],{"type":45,"value":986},{"type":45,"value":1706}," (cross-cutting only): pattern, behavior, edge-case, contract, performance, intent, warning, history, convention",{"type":39,"tag":69,"props":1708,"children":1710},{"id":1709},"trust-order",[1711],{"type":45,"value":1712},"Trust Order",{"type":39,"tag":92,"props":1714,"children":1715},{},[1716,1732,1747,1757,1768],{"type":39,"tag":96,"props":1717,"children":1718},{},[1719,1724,1726],{"type":39,"tag":52,"props":1720,"children":1722},{"className":1721},[],[1723],{"type":45,"value":226},{"type":45,"value":1725}," — highest trust, always ",{"type":39,"tag":52,"props":1727,"children":1729},{"className":1728},[],[1730],{"type":45,"value":1731},"verified",{"type":39,"tag":96,"props":1733,"children":1734},{},[1735,1740,1742],{"type":39,"tag":52,"props":1736,"children":1738},{"className":1737},[],[1739],{"type":45,"value":1647},{"type":45,"value":1741}," — always ",{"type":39,"tag":52,"props":1743,"children":1745},{"className":1744},[],[1746],{"type":45,"value":1731},{"type":39,"tag":96,"props":1748,"children":1749},{},[1750,1755],{"type":39,"tag":52,"props":1751,"children":1753},{"className":1752},[],[1754],{"type":45,"value":1731},{"type":45,"value":1756}," from exploration",{"type":39,"tag":96,"props":1758,"children":1759},{},[1760,1766],{"type":39,"tag":52,"props":1761,"children":1763},{"className":1762},[],[1764],{"type":45,"value":1765},"uncertain",{"type":45,"value":1767}," — not yet confirmed",{"type":39,"tag":96,"props":1769,"children":1770},{},[1771,1777],{"type":39,"tag":52,"props":1772,"children":1774},{"className":1773},[],[1775],{"type":45,"value":1776},"refuted",{"type":45,"value":1778}," — skip",{"type":39,"tag":69,"props":1780,"children":1782},{"id":1781},"five-reference-links-all-must-be-maintained",[1783],{"type":45,"value":1784},"Five Reference Links (all must be maintained)",{"type":39,"tag":92,"props":1786,"children":1787},{},[1788,1810,1834,1851,1875],{"type":39,"tag":96,"props":1789,"children":1790},{},[1791,1796,1797,1802,1804],{"type":39,"tag":79,"props":1792,"children":1793},{},[1794],{"type":45,"value":1795},"File mapping",{"type":45,"value":195},{"type":39,"tag":52,"props":1798,"children":1800},{"className":1799},[],[1801],{"type":45,"value":338},{"type":45,"value":1803}," ↔ ",{"type":39,"tag":52,"props":1805,"children":1807},{"className":1806},[],[1808],{"type":45,"value":1809},".shadow\u002Fsrc\u002Fauth.py.md",{"type":39,"tag":96,"props":1811,"children":1812},{},[1813,1818,1820,1825,1827,1832],{"type":39,"tag":79,"props":1814,"children":1815},{},[1816],{"type":45,"value":1817},"Symbol anchoring",{"type":45,"value":1819},": every source symbol has a ",{"type":39,"tag":52,"props":1821,"children":1823},{"className":1822},[],[1824],{"type":45,"value":883},{"type":45,"value":1826},"\u002F",{"type":39,"tag":52,"props":1828,"children":1830},{"className":1829},[],[1831],{"type":45,"value":896},{"type":45,"value":1833}," heading in its shadow",{"type":39,"tag":96,"props":1835,"children":1836},{},[1837,1842,1844,1849],{"type":39,"tag":79,"props":1838,"children":1839},{},[1840],{"type":45,"value":1841},"Also involves",{"type":45,"value":1843},": per-file discoveries list other ",{"type":39,"tag":52,"props":1845,"children":1847},{"className":1846},[],[1848],{"type":45,"value":234},{"type":45,"value":1850}," locations",{"type":39,"tag":96,"props":1852,"children":1853},{},[1854,1859,1861,1866,1868,1873],{"type":39,"tag":79,"props":1855,"children":1856},{},[1857],{"type":45,"value":1858},"Cross-ref back-pointers",{"type":45,"value":1860},": per-file ",{"type":39,"tag":52,"props":1862,"children":1864},{"className":1863},[],[1865],{"type":45,"value":906},{"type":45,"value":1867}," links to ",{"type":39,"tag":52,"props":1869,"children":1871},{"className":1870},[],[1872],{"type":45,"value":947},{"type":45,"value":1874}," entries",{"type":39,"tag":96,"props":1876,"children":1877},{},[1878,1883,1884,1889,1891,1897,1899,1904],{"type":39,"tag":79,"props":1879,"children":1880},{},[1881],{"type":45,"value":1882},"Cross-cutting refs",{"type":45,"value":195},{"type":39,"tag":52,"props":1885,"children":1887},{"className":1886},[],[1888],{"type":45,"value":947},{"type":45,"value":1890}," ",{"type":39,"tag":52,"props":1892,"children":1894},{"className":1893},[],[1895],{"type":45,"value":1896},"**Refs**:",{"type":45,"value":1898}," lists all involved ",{"type":39,"tag":52,"props":1900,"children":1902},{"className":1901},[],[1903],{"type":45,"value":234},{"type":45,"value":1850},{"type":39,"tag":48,"props":1906,"children":1907},{},[1908,1910,1916,1918,1924,1926,1932,1934,1939],{"type":45,"value":1909},"Links 4 and 5 are bidirectional: if ",{"type":39,"tag":52,"props":1911,"children":1913},{"className":1912},[],[1914],{"type":45,"value":1915},"_cross\u002Fdb-connection-lifecycle.md",{"type":45,"value":1917}," references\n",{"type":39,"tag":52,"props":1919,"children":1921},{"className":1920},[],[1922],{"type":45,"value":1923},"src\u002Fauth.py::fn",{"type":45,"value":1925},", then ",{"type":39,"tag":52,"props":1927,"children":1929},{"className":1928},[],[1930],{"type":45,"value":1931},"src\u002Fauth.py.md",{"type":45,"value":1933}," must list it in ",{"type":39,"tag":52,"props":1935,"children":1937},{"className":1936},[],[1938],{"type":45,"value":906},{"type":45,"value":1940},", and vice versa.",{"type":39,"tag":69,"props":1942,"children":1944},{"id":1943},"seven-invariants",[1945],{"type":45,"value":1946},"Seven Invariants",{"type":39,"tag":92,"props":1948,"children":1949},{},[1950,1960,1977,1994,2011,2030,2035],{"type":39,"tag":96,"props":1951,"children":1952},{},[1953,1955],{"type":45,"value":1954},"Every included source file has exactly one shadow at ",{"type":39,"tag":52,"props":1956,"children":1958},{"className":1957},[],[1959],{"type":45,"value":179},{"type":39,"tag":96,"props":1961,"children":1962},{},[1963,1965,1970,1971,1976],{"type":45,"value":1964},"Every symbol in source has a ",{"type":39,"tag":52,"props":1966,"children":1968},{"className":1967},[],[1969],{"type":45,"value":883},{"type":45,"value":1826},{"type":39,"tag":52,"props":1972,"children":1974},{"className":1973},[],[1975],{"type":45,"value":896},{"type":45,"value":1833},{"type":39,"tag":96,"props":1978,"children":1979},{},[1980,1982,1987,1989],{"type":45,"value":1981},"Per-file discoveries touching other files have ",{"type":39,"tag":52,"props":1983,"children":1985},{"className":1984},[],[1986],{"type":45,"value":1669},{"type":45,"value":1988}," with ",{"type":39,"tag":52,"props":1990,"children":1992},{"className":1991},[],[1993],{"type":45,"value":234},{"type":39,"tag":96,"props":1995,"children":1996},{},[1997,1999,2004,2006],{"type":45,"value":1998},"Cross-ref back-pointers match: ",{"type":39,"tag":52,"props":2000,"children":2002},{"className":2001},[],[2003],{"type":45,"value":947},{"type":45,"value":2005}," refs ↔ per-file ",{"type":39,"tag":52,"props":2007,"children":2009},{"className":2008},[],[2010],{"type":45,"value":906},{"type":39,"tag":96,"props":2012,"children":2013},{},[2014,2016,2021,2023,2028],{"type":45,"value":2015},"Every entry in ",{"type":39,"tag":52,"props":2017,"children":2019},{"className":2018},[],[2020],{"type":45,"value":906},{"type":45,"value":2022}," has a corresponding ",{"type":39,"tag":52,"props":2024,"children":2026},{"className":2025},[],[2027],{"type":45,"value":947},{"type":45,"value":2029}," file",{"type":39,"tag":96,"props":2031,"children":2032},{},[2033],{"type":45,"value":2034},"Cross-cutting filenames are unique (enforced by filesystem)",{"type":39,"tag":96,"props":2036,"children":2037},{},[2038],{"type":45,"value":2039},"No duplicate discoveries (same behavioral claim at same symbol)",{"type":39,"tag":48,"props":2041,"children":2042},{},[2043],{"type":45,"value":2044},"To audit a shadow for structural drift (invariant 3 format, invariants 4–5,\nplus enum and heading-format guards), locate the viewer script and run it:",{"type":39,"tag":284,"props":2046,"children":2050},{"className":2047,"code":2048,"language":2049,"meta":292,"style":292},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","VIEWER=\"\"\nfor DIR in .github\u002Fskills\u002Fshadow-frog-viewer .claude\u002Fskills\u002Fshadow-frog-viewer; do\n    [ -f \"$DIR\u002Fshadow-viewer.py\" ] && VIEWER=\"$DIR\u002Fshadow-viewer.py\" && break\ndone\npython3 \"$VIEWER\" --check-invariants\n","bash",[2051],{"type":39,"tag":52,"props":2052,"children":2053},{"__ignoreMap":292},[2054,2072,2110,2187,2195],{"type":39,"tag":362,"props":2055,"children":2056},{"class":364,"line":365},[2057,2062,2067],{"type":39,"tag":362,"props":2058,"children":2059},{"style":410},[2060],{"type":45,"value":2061},"VIEWER",{"type":39,"tag":362,"props":2063,"children":2064},{"style":369},[2065],{"type":45,"value":2066},"=",{"type":39,"tag":362,"props":2068,"children":2069},{"style":369},[2070],{"type":45,"value":2071},"\"\"\n",{"type":39,"tag":362,"props":2073,"children":2074},{"class":364,"line":381},[2075,2080,2085,2090,2095,2100,2105],{"type":39,"tag":362,"props":2076,"children":2077},{"style":519},[2078],{"type":45,"value":2079},"for",{"type":39,"tag":362,"props":2081,"children":2082},{"style":410},[2083],{"type":45,"value":2084}," DIR ",{"type":39,"tag":362,"props":2086,"children":2087},{"style":519},[2088],{"type":45,"value":2089},"in",{"type":39,"tag":362,"props":2091,"children":2092},{"style":557},[2093],{"type":45,"value":2094}," .github\u002Fskills\u002Fshadow-frog-viewer",{"type":39,"tag":362,"props":2096,"children":2097},{"style":557},[2098],{"type":45,"value":2099}," .claude\u002Fskills\u002Fshadow-frog-viewer",{"type":39,"tag":362,"props":2101,"children":2102},{"style":369},[2103],{"type":45,"value":2104},";",{"type":39,"tag":362,"props":2106,"children":2107},{"style":519},[2108],{"type":45,"value":2109}," do\n",{"type":39,"tag":362,"props":2111,"children":2112},{"class":364,"line":26},[2113,2118,2123,2128,2133,2138,2143,2148,2153,2158,2162,2166,2170,2174,2178,2182],{"type":39,"tag":362,"props":2114,"children":2115},{"style":369},[2116],{"type":45,"value":2117},"    [",{"type":39,"tag":362,"props":2119,"children":2120},{"style":369},[2121],{"type":45,"value":2122}," -f",{"type":39,"tag":362,"props":2124,"children":2125},{"style":369},[2126],{"type":45,"value":2127}," \"",{"type":39,"tag":362,"props":2129,"children":2130},{"style":410},[2131],{"type":45,"value":2132},"$DIR",{"type":39,"tag":362,"props":2134,"children":2135},{"style":557},[2136],{"type":45,"value":2137},"\u002Fshadow-viewer.py",{"type":39,"tag":362,"props":2139,"children":2140},{"style":369},[2141],{"type":45,"value":2142},"\"",{"type":39,"tag":362,"props":2144,"children":2145},{"style":369},[2146],{"type":45,"value":2147}," ]",{"type":39,"tag":362,"props":2149,"children":2150},{"style":369},[2151],{"type":45,"value":2152}," &&",{"type":39,"tag":362,"props":2154,"children":2155},{"style":410},[2156],{"type":45,"value":2157}," VIEWER",{"type":39,"tag":362,"props":2159,"children":2160},{"style":369},[2161],{"type":45,"value":2066},{"type":39,"tag":362,"props":2163,"children":2164},{"style":369},[2165],{"type":45,"value":2142},{"type":39,"tag":362,"props":2167,"children":2168},{"style":410},[2169],{"type":45,"value":2132},{"type":39,"tag":362,"props":2171,"children":2172},{"style":557},[2173],{"type":45,"value":2137},{"type":39,"tag":362,"props":2175,"children":2176},{"style":369},[2177],{"type":45,"value":2142},{"type":39,"tag":362,"props":2179,"children":2180},{"style":369},[2181],{"type":45,"value":2152},{"type":39,"tag":362,"props":2183,"children":2184},{"style":519},[2185],{"type":45,"value":2186}," break\n",{"type":39,"tag":362,"props":2188,"children":2189},{"class":364,"line":452},[2190],{"type":39,"tag":362,"props":2191,"children":2192},{"style":519},[2193],{"type":45,"value":2194},"done\n",{"type":39,"tag":362,"props":2196,"children":2197},{"class":364,"line":460},[2198,2203,2207,2212,2216],{"type":39,"tag":362,"props":2199,"children":2200},{"style":375},[2201],{"type":45,"value":2202},"python3",{"type":39,"tag":362,"props":2204,"children":2205},{"style":369},[2206],{"type":45,"value":2127},{"type":39,"tag":362,"props":2208,"children":2209},{"style":410},[2210],{"type":45,"value":2211},"$VIEWER",{"type":39,"tag":362,"props":2213,"children":2214},{"style":369},[2215],{"type":45,"value":2142},{"type":39,"tag":362,"props":2217,"children":2218},{"style":557},[2219],{"type":45,"value":2220}," --check-invariants\n",{"type":39,"tag":48,"props":2222,"children":2223},{},[2224,2226,2232],{"type":45,"value":2225},"Exits 0 if clean, 1 with one violation per line otherwise. Invariant 3 is\nchecked for anchor ",{"type":39,"tag":2227,"props":2228,"children":2229},"em",{},[2230],{"type":45,"value":2231},"format",{"type":45,"value":2233}," only (not existence of the referenced file or\nsymbol); invariants 1, 2, and 7 require source parsing \u002F semantic match and\nare not statically checked; invariant 6 is filesystem-enforced.",{"type":39,"tag":69,"props":2235,"children":2237},{"id":2236},"lookup-commands",[2238],{"type":45,"value":2239},"Lookup Commands",{"type":39,"tag":284,"props":2241,"children":2243},{"className":2047,"code":2242,"language":2049,"meta":292,"style":292},"# File's shadow\ncat .shadow\u002Fsrc\u002Fauth.py.md\n\n# Specific symbol's knowledge\ngrep -A 20 \"## \\`authenticate_user\\`\" .shadow\u002Fsrc\u002Fauth.py.md\n\n# Cross-cutting discoveries for a file\ngrep -rl \"src\u002Fauth.py::\" .shadow\u002F_cross\u002F\n\n# Search by topic\ngrep -rl \"error.handling\\|exception\" .shadow\u002F --include=\"*.md\"\n\n# All user-shared knowledge\ngrep -r \"source: user\" .shadow\u002F --include=\"*.md\"\n\n# Project-wide preferences\ncat .shadow\u002F_prefs.md\n\n# List all cross-cutting discovery files\nls .shadow\u002F_cross\u002F\n",[2244],{"type":39,"tag":52,"props":2245,"children":2246},{"__ignoreMap":292},[2247,2256,2269,2276,2284,2332,2339,2347,2377,2384,2392,2440,2447,2455,2499,2506,2514,2526,2533,2541],{"type":39,"tag":362,"props":2248,"children":2249},{"class":364,"line":365},[2250],{"type":39,"tag":362,"props":2251,"children":2253},{"style":2252},"--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic",[2254],{"type":45,"value":2255},"# File's shadow\n",{"type":39,"tag":362,"props":2257,"children":2258},{"class":364,"line":381},[2259,2264],{"type":39,"tag":362,"props":2260,"children":2261},{"style":375},[2262],{"type":45,"value":2263},"cat",{"type":39,"tag":362,"props":2265,"children":2266},{"style":557},[2267],{"type":45,"value":2268}," .shadow\u002Fsrc\u002Fauth.py.md\n",{"type":39,"tag":362,"props":2270,"children":2271},{"class":364,"line":26},[2272],{"type":39,"tag":362,"props":2273,"children":2274},{"emptyLinePlaceholder":385},[2275],{"type":45,"value":388},{"type":39,"tag":362,"props":2277,"children":2278},{"class":364,"line":452},[2279],{"type":39,"tag":362,"props":2280,"children":2281},{"style":2252},[2282],{"type":45,"value":2283},"# Specific symbol's knowledge\n",{"type":39,"tag":362,"props":2285,"children":2286},{"class":364,"line":460},[2287,2292,2297,2303,2307,2311,2316,2320,2324,2328],{"type":39,"tag":362,"props":2288,"children":2289},{"style":375},[2290],{"type":45,"value":2291},"grep",{"type":39,"tag":362,"props":2293,"children":2294},{"style":557},[2295],{"type":45,"value":2296}," -A",{"type":39,"tag":362,"props":2298,"children":2300},{"style":2299},"--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C",[2301],{"type":45,"value":2302}," 20",{"type":39,"tag":362,"props":2304,"children":2305},{"style":369},[2306],{"type":45,"value":2127},{"type":39,"tag":362,"props":2308,"children":2309},{"style":557},[2310],{"type":45,"value":466},{"type":39,"tag":362,"props":2312,"children":2313},{"style":410},[2314],{"type":45,"value":2315},"\\`",{"type":39,"tag":362,"props":2317,"children":2318},{"style":557},[2319],{"type":45,"value":665},{"type":39,"tag":362,"props":2321,"children":2322},{"style":410},[2323],{"type":45,"value":2315},{"type":39,"tag":362,"props":2325,"children":2326},{"style":369},[2327],{"type":45,"value":2142},{"type":39,"tag":362,"props":2329,"children":2330},{"style":557},[2331],{"type":45,"value":2268},{"type":39,"tag":362,"props":2333,"children":2334},{"class":364,"line":474},[2335],{"type":39,"tag":362,"props":2336,"children":2337},{"emptyLinePlaceholder":385},[2338],{"type":45,"value":388},{"type":39,"tag":362,"props":2340,"children":2341},{"class":364,"line":482},[2342],{"type":39,"tag":362,"props":2343,"children":2344},{"style":2252},[2345],{"type":45,"value":2346},"# Cross-cutting discoveries for a file\n",{"type":39,"tag":362,"props":2348,"children":2349},{"class":364,"line":515},[2350,2354,2359,2363,2368,2372],{"type":39,"tag":362,"props":2351,"children":2352},{"style":375},[2353],{"type":45,"value":2291},{"type":39,"tag":362,"props":2355,"children":2356},{"style":557},[2357],{"type":45,"value":2358}," -rl",{"type":39,"tag":362,"props":2360,"children":2361},{"style":369},[2362],{"type":45,"value":2127},{"type":39,"tag":362,"props":2364,"children":2365},{"style":557},[2366],{"type":45,"value":2367},"src\u002Fauth.py::",{"type":39,"tag":362,"props":2369,"children":2370},{"style":369},[2371],{"type":45,"value":2142},{"type":39,"tag":362,"props":2373,"children":2374},{"style":557},[2375],{"type":45,"value":2376}," .shadow\u002F_cross\u002F\n",{"type":39,"tag":362,"props":2378,"children":2379},{"class":364,"line":536},[2380],{"type":39,"tag":362,"props":2381,"children":2382},{"emptyLinePlaceholder":385},[2383],{"type":45,"value":388},{"type":39,"tag":362,"props":2385,"children":2386},{"class":364,"line":544},[2387],{"type":39,"tag":362,"props":2388,"children":2389},{"style":2252},[2390],{"type":45,"value":2391},"# Search by topic\n",{"type":39,"tag":362,"props":2393,"children":2394},{"class":364,"line":568},[2395,2399,2403,2407,2412,2416,2421,2426,2430,2435],{"type":39,"tag":362,"props":2396,"children":2397},{"style":375},[2398],{"type":45,"value":2291},{"type":39,"tag":362,"props":2400,"children":2401},{"style":557},[2402],{"type":45,"value":2358},{"type":39,"tag":362,"props":2404,"children":2405},{"style":369},[2406],{"type":45,"value":2127},{"type":39,"tag":362,"props":2408,"children":2409},{"style":557},[2410],{"type":45,"value":2411},"error.handling\\|exception",{"type":39,"tag":362,"props":2413,"children":2414},{"style":369},[2415],{"type":45,"value":2142},{"type":39,"tag":362,"props":2417,"children":2418},{"style":557},[2419],{"type":45,"value":2420}," .shadow\u002F",{"type":39,"tag":362,"props":2422,"children":2423},{"style":557},[2424],{"type":45,"value":2425}," --include=",{"type":39,"tag":362,"props":2427,"children":2428},{"style":369},[2429],{"type":45,"value":2142},{"type":39,"tag":362,"props":2431,"children":2432},{"style":557},[2433],{"type":45,"value":2434},"*.md",{"type":39,"tag":362,"props":2436,"children":2437},{"style":369},[2438],{"type":45,"value":2439},"\"\n",{"type":39,"tag":362,"props":2441,"children":2442},{"class":364,"line":576},[2443],{"type":39,"tag":362,"props":2444,"children":2445},{"emptyLinePlaceholder":385},[2446],{"type":45,"value":388},{"type":39,"tag":362,"props":2448,"children":2449},{"class":364,"line":22},[2450],{"type":39,"tag":362,"props":2451,"children":2452},{"style":2252},[2453],{"type":45,"value":2454},"# All user-shared knowledge\n",{"type":39,"tag":362,"props":2456,"children":2457},{"class":364,"line":605},[2458,2462,2467,2471,2475,2479,2483,2487,2491,2495],{"type":39,"tag":362,"props":2459,"children":2460},{"style":375},[2461],{"type":45,"value":2291},{"type":39,"tag":362,"props":2463,"children":2464},{"style":557},[2465],{"type":45,"value":2466}," -r",{"type":39,"tag":362,"props":2468,"children":2469},{"style":369},[2470],{"type":45,"value":2127},{"type":39,"tag":362,"props":2472,"children":2473},{"style":557},[2474],{"type":45,"value":226},{"type":39,"tag":362,"props":2476,"children":2477},{"style":369},[2478],{"type":45,"value":2142},{"type":39,"tag":362,"props":2480,"children":2481},{"style":557},[2482],{"type":45,"value":2420},{"type":39,"tag":362,"props":2484,"children":2485},{"style":557},[2486],{"type":45,"value":2425},{"type":39,"tag":362,"props":2488,"children":2489},{"style":369},[2490],{"type":45,"value":2142},{"type":39,"tag":362,"props":2492,"children":2493},{"style":557},[2494],{"type":45,"value":2434},{"type":39,"tag":362,"props":2496,"children":2497},{"style":369},[2498],{"type":45,"value":2439},{"type":39,"tag":362,"props":2500,"children":2501},{"class":364,"line":618},[2502],{"type":39,"tag":362,"props":2503,"children":2504},{"emptyLinePlaceholder":385},[2505],{"type":45,"value":388},{"type":39,"tag":362,"props":2507,"children":2508},{"class":364,"line":627},[2509],{"type":39,"tag":362,"props":2510,"children":2511},{"style":2252},[2512],{"type":45,"value":2513},"# Project-wide preferences\n",{"type":39,"tag":362,"props":2515,"children":2516},{"class":364,"line":643},[2517,2521],{"type":39,"tag":362,"props":2518,"children":2519},{"style":375},[2520],{"type":45,"value":2263},{"type":39,"tag":362,"props":2522,"children":2523},{"style":557},[2524],{"type":45,"value":2525}," .shadow\u002F_prefs.md\n",{"type":39,"tag":362,"props":2527,"children":2528},{"class":364,"line":651},[2529],{"type":39,"tag":362,"props":2530,"children":2531},{"emptyLinePlaceholder":385},[2532],{"type":45,"value":388},{"type":39,"tag":362,"props":2534,"children":2535},{"class":364,"line":672},[2536],{"type":39,"tag":362,"props":2537,"children":2538},{"style":2252},[2539],{"type":45,"value":2540},"# List all cross-cutting discovery files\n",{"type":39,"tag":362,"props":2542,"children":2543},{"class":364,"line":680},[2544,2549],{"type":39,"tag":362,"props":2545,"children":2546},{"style":375},[2547],{"type":45,"value":2548},"ls",{"type":39,"tag":362,"props":2550,"children":2551},{"style":557},[2552],{"type":45,"value":2376},{"type":39,"tag":69,"props":2554,"children":2556},{"id":2555},"verification",[2557],{"type":45,"value":2558},"Verification",{"type":39,"tag":48,"props":2560,"children":2561},{},[2562],{"type":45,"value":2563},"Two methods, use whichever fits the claim:",{"type":39,"tag":48,"props":2565,"children":2566},{},[2567,2572],{"type":39,"tag":79,"props":2568,"children":2569},{},[2570],{"type":45,"value":2571},"Observe-based",{"type":45,"value":2573}," (for simpler claims — code reading suffices):",{"type":39,"tag":92,"props":2575,"children":2576},{},[2577,2587,2592],{"type":39,"tag":96,"props":2578,"children":2579},{},[2580,2582],{"type":45,"value":2581},"Read the source code at the relevant ",{"type":39,"tag":52,"props":2583,"children":2585},{"className":2584},[],[2586],{"type":45,"value":234},{"type":39,"tag":96,"props":2588,"children":2589},{},[2590],{"type":45,"value":2591},"Trace the logic: does the behavioral claim hold?",{"type":39,"tag":96,"props":2593,"children":2594},{},[2595,2597,2602,2604,2609,2611,2616],{"type":45,"value":2596},"If confirmed → ",{"type":39,"tag":52,"props":2598,"children":2600},{"className":2599},[],[2601],{"type":45,"value":1731},{"type":45,"value":2603},". If contradicted → ",{"type":39,"tag":52,"props":2605,"children":2607},{"className":2606},[],[2608],{"type":45,"value":1776},{"type":45,"value":2610},". If unclear → ",{"type":39,"tag":52,"props":2612,"children":2614},{"className":2613},[],[2615],{"type":45,"value":1765},{"type":45,"value":2617},".",{"type":39,"tag":48,"props":2619,"children":2620},{},[2621,2626],{"type":39,"tag":79,"props":2622,"children":2623},{},[2624],{"type":45,"value":2625},"Do-based",{"type":45,"value":2627}," (for harder claims — requires execution):",{"type":39,"tag":92,"props":2629,"children":2630},{},[2631,2636,2641],{"type":39,"tag":96,"props":2632,"children":2633},{},[2634],{"type":45,"value":2635},"Write a short verification script (test, assertion, or probe) that would\nconfirm or refute the claim",{"type":39,"tag":96,"props":2637,"children":2638},{},[2639],{"type":45,"value":2640},"Run it",{"type":39,"tag":96,"props":2642,"children":2643},{},[2644,2646,2651,2653],{"type":45,"value":2645},"Based on the result → ",{"type":39,"tag":52,"props":2647,"children":2649},{"className":2648},[],[2650],{"type":45,"value":1731},{"type":45,"value":2652}," or ",{"type":39,"tag":52,"props":2654,"children":2656},{"className":2655},[],[2657],{"type":45,"value":1776},{"type":39,"tag":48,"props":2659,"children":2660},{},[2661],{"type":45,"value":2662},"Prefer do-based for claims about runtime behavior, performance, error handling\npaths, or race conditions. Prefer observe-based for claims about code structure,\ntypes, or static properties.",{"type":39,"tag":69,"props":2664,"children":2666},{"id":2665},"dedup-and-writing-rules",[2667],{"type":45,"value":2668},"Dedup and Writing Rules",{"type":39,"tag":48,"props":2670,"children":2671},{},[2672],{"type":45,"value":2673},"Before writing any discovery, follow this procedure:",{"type":39,"tag":92,"props":2675,"children":2676},{},[2677,2700,2718,2723],{"type":39,"tag":96,"props":2678,"children":2679},{},[2680,2685,2687,2692,2694,2699],{"type":39,"tag":79,"props":2681,"children":2682},{},[2683],{"type":45,"value":2684},"Read before write",{"type":45,"value":2686},": Read all existing discoveries under the target\n",{"type":39,"tag":52,"props":2688,"children":2690},{"className":2689},[],[2691],{"type":45,"value":234},{"type":45,"value":2693},". If an existing discovery makes the same behavioral\nclaim (even if worded differently) → update the existing one. If the\nnew one extends an existing one → merge into a single richer entry.\nIf they conflict → investigate the code, keep the correct one, mark\nthe other ",{"type":39,"tag":52,"props":2695,"children":2697},{"className":2696},[],[2698],{"type":45,"value":1776},{"type":45,"value":2617},{"type":39,"tag":96,"props":2701,"children":2702},{},[2703,2708,2710,2716],{"type":39,"tag":79,"props":2704,"children":2705},{},[2706],{"type":45,"value":2707},"Append, don't replace",{"type":45,"value":2709},": If the symbol already has discoveries,\nappend your new one after them. If there is a ",{"type":39,"tag":52,"props":2711,"children":2713},{"className":2712},[],[2714],{"type":45,"value":2715},"_No discoveries yet._",{"type":45,"value":2717},"\nplaceholder, remove it and write your discovery. Never use the\nplaceholder as an edit anchor if it's already gone — read the file first.",{"type":39,"tag":96,"props":2719,"children":2720},{},[2721],{"type":45,"value":2722},"Write in canonical format (see Discovery Format above)",{"type":39,"tag":96,"props":2724,"children":2725},{},[2726,2731],{"type":39,"tag":79,"props":2727,"children":2728},{},[2729],{"type":45,"value":2730},"Fix bad format",{"type":45,"value":2732},": if you see any existing content that doesn't\nfollow the canonical format, fix it in place",{"type":39,"tag":48,"props":2734,"children":2735},{},[2736,2738,2743,2745,2750,2752,2757,2759,2764,2766,2771],{"type":45,"value":2737},"For cross-cutting, search ",{"type":39,"tag":52,"props":2739,"children":2741},{"className":2740},[],[2742],{"type":45,"value":126},{"type":45,"value":2744}," for overlapping ",{"type":39,"tag":52,"props":2746,"children":2748},{"className":2747},[],[2749],{"type":45,"value":1896},{"type":45,"value":2751}," sets\nbefore creating a new entry. Only create ",{"type":39,"tag":52,"props":2753,"children":2755},{"className":2754},[],[2756],{"type":45,"value":947},{"type":45,"value":2758}," for\ndiscoveries spanning ",{"type":39,"tag":79,"props":2760,"children":2761},{},[2762],{"type":45,"value":2763},"3+ files",{"type":45,"value":2765}," — otherwise use per-file entries with\n",{"type":39,"tag":52,"props":2767,"children":2769},{"className":2768},[],[2770],{"type":45,"value":1669},{"type":45,"value":2772}," references.",{"type":39,"tag":69,"props":2774,"children":2776},{"id":2775},"related-skills",[2777],{"type":45,"value":2778},"Related Skills",{"type":39,"tag":870,"props":2780,"children":2781},{},[2782,2800,2810,2821,2832],{"type":39,"tag":96,"props":2783,"children":2784},{},[2785,2791,2793,2798],{"type":39,"tag":52,"props":2786,"children":2788},{"className":2787},[],[2789],{"type":45,"value":2790},"\u002Fshadow-frog-init",{"type":45,"value":2792}," — create ",{"type":39,"tag":52,"props":2794,"children":2796},{"className":2795},[],[2797],{"type":45,"value":57},{"type":45,"value":2799}," for a new repo",{"type":39,"tag":96,"props":2801,"children":2802},{},[2803,2808],{"type":39,"tag":52,"props":2804,"children":2806},{"className":2805},[],[2807],{"type":45,"value":276},{"type":45,"value":2809}," — refresh shadows after changes or from conversation",{"type":39,"tag":96,"props":2811,"children":2812},{},[2813,2819],{"type":39,"tag":52,"props":2814,"children":2816},{"className":2815},[],[2817],{"type":45,"value":2818},"\u002Fshadow-frog-dream",{"type":45,"value":2820}," — autonomous exploration and experimentation while user is AFK",{"type":39,"tag":96,"props":2822,"children":2823},{},[2824,2830],{"type":39,"tag":52,"props":2825,"children":2827},{"className":2826},[],[2828],{"type":45,"value":2829},"\u002Fshadow-frog-meditate",{"type":45,"value":2831}," — deduplicate, merge, and resolve conflicting discoveries",{"type":39,"tag":96,"props":2833,"children":2834},{},[2835,2841],{"type":39,"tag":52,"props":2836,"children":2838},{"className":2837},[],[2839],{"type":45,"value":2840},"\u002Fshadow-frog-viewer",{"type":45,"value":2842}," — browse and query the shadow (overview, search, preferences, recent)",{"type":39,"tag":2844,"props":2845,"children":2846},"style",{},[2847],{"type":45,"value":2848},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"items":2850,"total":26},[2851,2857,2875],{"slug":4,"name":4,"fn":5,"description":6,"org":2852,"tags":2853,"stars":22,"repoUrl":23,"updatedAt":24},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2854,2855,2856],{"name":20,"slug":21,"type":15},{"name":17,"slug":18,"type":15},{"name":13,"slug":14,"type":15},{"slug":2858,"name":2858,"fn":2859,"description":2860,"org":2861,"tags":2862,"stars":22,"repoUrl":23,"updatedAt":2874},"shadow-frog-dream","run autonomous experimentation sessions","Run autonomous experimentation while the user is AFK. Uses 6 investigation categories (investigation, bug hunting, feature design, refactoring, optimization, security audit) to systematically discover non-obvious behaviors. Every task is an experiment — implement in worktrees, commit to persistent dream branches, and push to the fork. Dreams compound across sessions: future experiments branch from prior dream branches, building a tree of progressively deeper work. Invoke when the user is AFK or asks for a dream run.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2863,2866,2869,2872],{"name":2864,"slug":2865,"type":15},"Agents","agents",{"name":2867,"slug":2868,"type":15},"Automation","automation",{"name":2870,"slug":2871,"type":15},"Debugging","debugging",{"name":2873,"slug":1526,"type":15},"Security","2026-07-03T16:31:54.732639",{"slug":2876,"name":2876,"fn":2877,"description":2878,"org":2879,"tags":2880,"stars":22,"repoUrl":23,"updatedAt":2886},"shadow-frog-meditate","clean and consolidate shadow knowledge base","Clean and consolidate the shadow knowledge base. Scans all shadow files for duplicate discoveries (same claim, different wording), near-duplicates (one extends another), and conflicting entries (contradicting claims). Merges duplicates, resolves conflicts by investigating the code, and asks the user only when resolution is unclear. Invoke periodically to keep the shadow focused and free of noise.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2881,2884,2885],{"name":2882,"slug":2883,"type":15},"Data Cleaning","data-cleaning",{"name":13,"slug":14,"type":15},{"name":9,"slug":8,"type":15},"2026-07-03T16:31:56.106085",{"items":2888,"total":3077},[2889,2909,2928,2949,2962,2979,2990,3003,3018,3033,3052,3065],{"slug":2890,"name":2890,"fn":2891,"description":2892,"org":2893,"tags":2894,"stars":2906,"repoUrl":2907,"updatedAt":2908},"rushstack-best-practices","manage Rush monorepos with best practices","Provides best practices and guidance for working with Rush monorepos. Use when the user is working in a Rush-based repository, asks about Rush commands (install, update, build, rebuild), needs help with project selection, dependency management, build caching, subspace configuration, or troubleshooting Rush-specific issues.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2895,2896,2899,2900,2903],{"name":17,"slug":18,"type":15},{"name":2897,"slug":2898,"type":15},"Local Development","local-development",{"name":9,"slug":8,"type":15},{"name":2901,"slug":2902,"type":15},"Project Management","project-management",{"name":2904,"slug":2905,"type":15},"Rush","rush",6484,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frushstack","2026-04-06T18:34:44.965032",{"slug":2910,"name":2910,"fn":2911,"description":2912,"org":2913,"tags":2914,"stars":2925,"repoUrl":2926,"updatedAt":2927},"azure-ai-agents-persistent-dotnet","build AI agents with Azure .NET SDK","Azure AI Agents Persistent SDK for .NET. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Use for agent CRUD, conversation threads, streaming responses, function calling, file search, and code interpreter. Triggers: \"PersistentAgentsClient\", \"persistent agents\", \"agent threads\", \"agent runs\", \"streaming agents\", \"function calling agents .NET\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2915,2918,2919,2922],{"name":2916,"slug":2917,"type":15},".NET","net",{"name":2864,"slug":2865,"type":15},{"name":2920,"slug":2921,"type":15},"Azure","azure",{"name":2923,"slug":2924,"type":15},"LLM","llm",2804,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills","2026-07-03T16:32:10.297433",{"slug":2929,"name":2929,"fn":2930,"description":2931,"org":2932,"tags":2933,"stars":2925,"repoUrl":2926,"updatedAt":2948},"azure-ai-anomalydetector-java","build anomaly detection applications with Java","Build anomaly detection applications with Azure AI Anomaly Detector SDK for Java. Use when implementing univariate\u002Fmultivariate anomaly detection, time-series analysis, or AI-powered monitoring.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2934,2937,2938,2941,2944,2945],{"name":2935,"slug":2936,"type":15},"Analytics","analytics",{"name":2920,"slug":2921,"type":15},{"name":2939,"slug":2940,"type":15},"Data Analysis","data-analysis",{"name":2942,"slug":2943,"type":15},"Java","java",{"name":9,"slug":8,"type":15},{"name":2946,"slug":2947,"type":15},"Monitoring","monitoring","2026-05-13T06:14:16.261754",{"slug":2950,"name":2950,"fn":2951,"description":2952,"org":2953,"tags":2954,"stars":2925,"repoUrl":2926,"updatedAt":2961},"azure-ai-contentsafety-java","build content moderation applications with Azure AI","Build content moderation applications with Azure AI Content Safety SDK for Java. Use when implementing text\u002Fimage analysis, blocklist management, or harm detection for hate, violence, sexual content, and self-harm.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2955,2958,2959,2960],{"name":2956,"slug":2957,"type":15},"AI Infrastructure","ai-infrastructure",{"name":2920,"slug":2921,"type":15},{"name":2942,"slug":2943,"type":15},{"name":2873,"slug":1526,"type":15},"2026-07-07T06:53:31.293235",{"slug":2963,"name":2963,"fn":2964,"description":2965,"org":2966,"tags":2967,"stars":2925,"repoUrl":2926,"updatedAt":2978},"azure-ai-contentsafety-py","detect harmful content with Azure AI Content Safety","Azure AI Content Safety SDK for Python. Use for detecting harmful content in text and images with multi-severity classification.\nTriggers: \"azure-ai-contentsafety\", \"ContentSafetyClient\", \"content moderation\", \"harmful content\", \"text analysis\", \"image analysis\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2968,2969,2972,2973,2974,2977],{"name":2920,"slug":2921,"type":15},{"name":2970,"slug":2971,"type":15},"Compliance","compliance",{"name":2923,"slug":2924,"type":15},{"name":9,"slug":8,"type":15},{"name":2975,"slug":2976,"type":15},"Python","python",{"name":2873,"slug":1526,"type":15},"2026-07-18T05:14:23.017504",{"slug":2980,"name":2980,"fn":2981,"description":2982,"org":2983,"tags":2984,"stars":2925,"repoUrl":2926,"updatedAt":2989},"azure-ai-language-conversations-py","implement conversational language understanding with Python","Implement Conversational Language Understanding (CLU) using the azure-ai-language-conversations Python SDK. Use when working with ConversationAnalysisClient to analyze conversation intent and entities, building NLP features, or integrating language understanding into applications.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2985,2986,2987,2988],{"name":2935,"slug":2936,"type":15},{"name":2920,"slug":2921,"type":15},{"name":2923,"slug":2924,"type":15},{"name":2975,"slug":2976,"type":15},"2026-07-31T05:54:29.068751",{"slug":2991,"name":2991,"fn":2992,"description":2993,"org":2994,"tags":2995,"stars":2925,"repoUrl":2926,"updatedAt":3002},"azure-ai-translation-text-py","translate text using Azure AI services","Azure AI Text Translation SDK for real-time text translation, transliteration, language detection, and dictionary lookup. Use for translating text content in applications.\nTriggers: \"text translation\", \"translator\", \"translate text\", \"transliterate\", \"TextTranslationClient\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[2996,2999,3000,3001],{"name":2997,"slug":2998,"type":15},"API Development","api-development",{"name":2920,"slug":2921,"type":15},{"name":9,"slug":8,"type":15},{"name":2975,"slug":2976,"type":15},"2026-07-18T05:14:16.988376",{"slug":3004,"name":3004,"fn":3005,"description":3006,"org":3007,"tags":3008,"stars":2925,"repoUrl":2926,"updatedAt":3017},"azure-ai-vision-imageanalysis-py","analyze images with Azure AI Vision","Azure AI Vision Image Analysis SDK for captions, tags, objects, OCR, people detection, and smart cropping. Use for computer vision and image understanding tasks.\nTriggers: \"image analysis\", \"computer vision\", \"OCR\", \"object detection\", \"ImageAnalysisClient\", \"image caption\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3009,3010,3013,3016],{"name":2920,"slug":2921,"type":15},{"name":3011,"slug":3012,"type":15},"Computer Vision","computer-vision",{"name":3014,"slug":3015,"type":15},"Images","images",{"name":2975,"slug":2976,"type":15},"2026-07-18T05:14:18.007737",{"slug":3019,"name":3019,"fn":3020,"description":3021,"org":3022,"tags":3023,"stars":2925,"repoUrl":2926,"updatedAt":3032},"azure-appconfiguration-java","manage configuration with Azure App Configuration","Azure App Configuration SDK for Java. Centralized application configuration management with key-value settings, feature flags, and snapshots.\nTriggers: \"ConfigurationClient java\", \"app configuration java\", \"feature flag java\", \"configuration setting java\", \"azure config java\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3024,3025,3028,3031],{"name":2920,"slug":2921,"type":15},{"name":3026,"slug":3027,"type":15},"Configuration","configuration",{"name":3029,"slug":3030,"type":15},"Feature Flags","feature-flags",{"name":2942,"slug":2943,"type":15},"2026-07-03T16:32:01.278468",{"slug":3034,"name":3034,"fn":3035,"description":3036,"org":3037,"tags":3038,"stars":2925,"repoUrl":2926,"updatedAt":3051},"azure-cosmos-rust","build applications with Azure Cosmos DB","Azure Cosmos DB library for Rust (NoSQL API). Document CRUD, containers, and globally distributed data.\nTriggers: \"cosmos db rust\", \"CosmosClient rust\", \"document crud rust\", \"NoSQL rust\", \"partition key rust\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3039,3042,3045,3048],{"name":3040,"slug":3041,"type":15},"Cosmos DB","cosmos-db",{"name":3043,"slug":3044,"type":15},"Database","database",{"name":3046,"slug":3047,"type":15},"NoSQL","nosql",{"name":3049,"slug":3050,"type":15},"Rust","rust","2026-07-31T05:54:27.021432",{"slug":3053,"name":3053,"fn":3035,"description":3054,"org":3055,"tags":3056,"stars":2925,"repoUrl":2926,"updatedAt":3064},"azure-cosmos-ts","Azure Cosmos DB JavaScript\u002FTypeScript SDK (@azure\u002Fcosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: \"Cosmos DB\", \"@azure\u002Fcosmos\", \"CosmosClient\", \"document CRUD\", \"NoSQL queries\", \"bulk operations\", \"partition key\", \"container.items\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3057,3058,3059,3060,3061],{"name":3040,"slug":3041,"type":15},{"name":3043,"slug":3044,"type":15},{"name":9,"slug":8,"type":15},{"name":3046,"slug":3047,"type":15},{"name":3062,"slug":3063,"type":15},"TypeScript","typescript","2026-07-03T16:31:19.368382",{"slug":3066,"name":3066,"fn":3067,"description":3068,"org":3069,"tags":3070,"stars":2925,"repoUrl":2926,"updatedAt":3076},"azure-data-tables-java","build table storage applications with Java","Build table storage applications with Azure Tables SDK for Java. Use when working with Azure Table Storage or Cosmos DB Table API for NoSQL key-value data, schemaless storage, or structured data at scale.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[3071,3072,3073,3074,3075],{"name":2920,"slug":2921,"type":15},{"name":3040,"slug":3041,"type":15},{"name":3043,"slug":3044,"type":15},{"name":2942,"slug":2943,"type":15},{"name":3046,"slug":3047,"type":15},"2026-05-13T06:14:17.582229",267]