[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M73CG8TS340917Y0GFV3GAS1":3,"skill-same:01M73CG8TS340917Y0GFV3GAS1":60},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":38,"commitSha":39,"skillDirectory":40,"forksCount":41,"repositoryHtmlUrl":42,"repositoryHomepageUrl":6,"ownerHtmlUrl":43,"ownerBlogUrl":6,"ownerDescription":44,"updatedAt":45,"install":46,"resources":59},"01M73CG8TS340917Y0GFV3GAS1","trail",null,"This repo is indexed by the trail repo-context-graph. For ANY task here, whether understanding how something works, finding where code lives, tracing what calls a symbol or what a change breaks, or scoping an edit, get your context from trail before grepping or reading source files.","5throck\u002Fai-workspace-standards","5throck","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F10958964?v=4","01M73BFEH0V0VS483TW4JD49JW","01M73BFEJ5VQZJHJSFTVPAZGDM",25,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Fskills\u002Ftrail\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: trail\ndescription: >\n  This repo is indexed by the trail repo-context-graph. For ANY task here, whether\n  understanding how something works, finding where code lives, tracing what calls a\n  symbol or what a change breaks, or scoping an edit, get your context from trail\n  before grepping or reading source files.\nversion: 1.2.0\nlast_reviewed: 2026-11-08\nstatus: active\nscope: common\nl2_propagate: false\nmirror: false\nowner: pm\nprerequisites: trail CLI\nmetadata:\n  type: process\n  triggers:\n    - trail\n    - graft\n    - repo context graph\n    - find where code lives\n    - what calls this symbol\n    - blast radius\n---\n\n# trail\n\n> **Alias note**: renamed from graft (vendor rename 0.28, `@trailhq\u002Ftrail-code`);\n> `graft …` commands in older references read as `trail …`. On repos not yet\n> migrated the binary and index still carry their pre-rename names (`graft`,\n> `graft\u002F`) — same tools, same flags; run the pre-rename spelling there, or run\n> the vendor upgrade first (`trail upgrade` auto-runs `trail init` and rewrites\n> the repo surfaces to trail-era naming).\n\nThe trail index holds a graph of this repo: small markdown nodes that each explain\none part in prose and name the exact `file:line` spans they cover, plus a wiring\ngraph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding\nthat understanding by reading source costs thousands, and misses the edges.\n\nEvery command below is `$0`, needs no API key, and returns in under a second.\nThere are six of them. **Pick the one that fits the task, run it, act on the\nanswer; don't chain tools hoping for more. Most tasks need one call.**\n\n## The tools\n\n### 1 · `trail ask \"\u003Cquestion>\" --source`: locate + understand (the default)\nRanked retrieval over the graph, routed automatically between prose nodes and\nthe wiring graph, returning the top hits with exact `file:line`.\n- `--source` inlines the code at each hit, the ≤8-line **crux** of each\n  definition, so the result IS the code you need, no follow-up file read. Add\n  `--full` only when the crux is too small to act on.\n- `--in \u003Cpath>` narrows to a subtree before ranking; `-n N` caps results (default 8).\n- **Use it when** the question is conceptual or locational: \"how does auth\n  work\", \"where is rate-limiting handled\", \"what assembles the request pipeline\".\n- One ask usually answers. A genuinely multi-part question needs one ask per\n  distinct sub-aspect, never the same question reworded. Few or weak hits mean\n  switch tool (grep \u002F skeleton \u002F callers), don't re-ask.\n\n### 2 · `trail grep \"\u003Cpattern>\"`: exhaustive find\nRegex (or `--fixed` for a literal) over every indexed file, hits **grouped by\nenclosing symbol** and ranked by coupling; it also reports files it couldn't read.\n- **Use it when** you need every occurrence: all call sites, all uses of a\n  constant, all providers. `ask` is ranked top-N and *will* miss instances;\n  grep won't. One grep replaces a spray of asks.\n- Search a **short symbol name or literal**, not a full guessed signature: an\n  over-specific regex (`func (s *Server) GenerateHandler`) returns nothing even\n  when the code is indexed. If a grep misses, **loosen it** (drop the receiver\n  and signature, keep the bare name) and retry `trail grep` — do NOT switch to\n  raw `grep -rn`, which is slower and unranked.\n- `-i` case-insensitive; `--in \u003Cpath>` scopes to a subtree. Raw `grep -rn` is\n  only for files trail genuinely doesn't index (docs, configs, brand-new files).\n\n### 3 · `trail skeleton \u003Cfile>`: a file's API at a glance\nSignatures-only view of one file (every function \u002F method \u002F type with its span)\nin ~200 tokens, ~10x cheaper than reading the file.\n- **Use it when** you need \"what's in this file \u002F what can I call here\" before\n  editing or wiring into it. One skeleton is the whole answer for a file; don't\n  re-skeleton the same file, and don't skeleton every file `map` already named.\n\n### 4 · `trail callers \u003Csymbol>`: the exact edges\nPrecomputed call\u002Freference edges, not a text search. Symbol can be bare\n(`Foo`), qualified (`Class.method`), or package-qualified (`pkg.Fn`).\n- default `--direction in`: **who calls\u002Freferences** this; run before you\n  rename, delete, or change its signature.\n- `--direction out`: **what this symbol itself calls\u002Fdepends on** (the old `callees`).\n- `--depth N`: walk transitively N hops for the **full blast radius** (the old\n  `impact`); `--depth 2` is the usual \"what breaks if I touch this\".\n- `--depth all`: the **entire connected closure** — every source reachable\n  through the edges. Reach for this before a **refactor, rename, or any\n  multi-file change**: it surfaces the sibling and downstream files (platform\n  variants, a module you must split out) that a single-file edit would miss.\n\n### 5 · `trail map`: orientation for an unfamiliar repo or area\nA token-budgeted tour: directory clusters, per-directory hubs, and global\nhotspots, straight from the wiring graph.\n- **Use it when** you land in a repo cold or are asked for \"the architecture\".\n  `map` alone is the answer: read the hub cards it names; do NOT then skeleton\n  or ask your way through every subsystem it lists. `--max-dirs N` widens it.\n\n### 6 · Lifecycle: `trail build` \u002F `trail check`\nEvery tool above refreshes the graph itself before answering, so what those tools\nreturn always describes the code as it is right now — including edits you just made\nand have not committed. You do **not** need to run `build` after editing.\n\n**The AGENTS.md trail block is tool-managed** (verified 2026-10-04, T-20261004-001,\ngraft-era mechanics; trail-era rewrites keep the same behavior):\nthe Claude Code session-start hook runs the tool's upkeep, whose `reconcileWiring`\ntreats a hand-deleted instruction block as accidental loss and re-appends it\n(`upsertSection` on the tool's markers — graft-era installs used\n`graft:start`\u002F`graft:end`; a `trail init` rewrite swaps them for the trail\nequivalents). Hand-editing or withdrawing the block from AGENTS.md is therefore\nundone at the next session start; the durable removal is\n`trail uninstall -y --keep-cache` (graft-era binaries: `graft uninstall`),\nwiring only — keeps the index directory and its cache. The block text lives in\nthe tool package (`hosts\u002Finstructions.js instructionBody()`); this SKILL.md is\nthe doctrine SSOT for tool behavior — the AGENTS.md block is a package-rendered\nsummary.\n\nOne caveat, if you `grep` the markdown under the index directory directly\n(`graft\u002F` pre-rename, `.trail\u002Fcache\u002F` after `trail init`): those cards are a\nprojection, rebuilt at the end of the turn rather than on each query, so after an edit\nthey can lag. The tools above never do — prefer them, and treat a card's spans as\nstale if you have edited that file this turn.\n\n`build` is for the LLM layer (`--deep` adds a concept map; skip unless asked);\n`check` fails when the index is stale, for CI.\n\n## Scenarios: the shortest path through a coding task\n\n| When you're… | Reach for | Calls |\n|---|---|---|\n| Onboarding \u002F \"explain this codebase\" | `trail map`, then read the named hub cards | 1 |\n| Understanding a flow (\"how does X work\") | `trail ask \"\u003Cflow>\" --source` | 1 |\n| Finding where a change belongs | `trail ask \"where is \u003Cbehavior>\" --source` | 1 |\n| Editing a symbol you can already name | `trail grep \"\u003Csymbol>\"`, edit at the `file:line` (skip `ask` — you know where it is) | 1 |\n| Renaming \u002F deleting \u002F changing a signature | `trail callers \u003Csym> --depth 2` first | 1 |\n| Refactor \u002F multi-file change (before editing) | `trail callers \u003Csym> --depth all` — map every connected file, don't stop at the first | 1 |\n| \"What does this depend on?\" | `trail callers \u003Csym> --direction out` | 1 |\n| Finding every occurrence of a pattern | `trail grep \"\u003Cliteral>\"` | 1 |\n| \"What's the API of this file?\" | `trail skeleton \u003Cfile>` | 1 |\n| Debugging a failure in area X | `trail ask \"\u003Csymptom>\" --source`, then `callers` on the suspect | 1–2 |\n| Judging a diff's risk before merge | `trail callers \u003Cchanged sym> --depth 2` | 1 \u002F symbol |\n| Working inside one repo of a monorepo | add `--in \u003Cscope>\u002F` to ask \u002F grep \u002F callers | n\u002Fa |\n\nIn a multi-repo workspace, trail ranks fairly so the biggest repo can't drown\nthe rest, and every hit carries a `[scope\u002F]` label naming its sub-project; when\nyou already know where you're working, narrow with `trail ask \"\u003Ctask>\" --in \u003Cscope>\u002F`.\n\n## Spend the fewest calls\n- A node's `covers:` list already gives exact `file:line` for every symbol, so\n  cite straight from it. The spans are generated from source and authoritative;\n  don't re-open or re-grep files to \"double-check\".\n- When the task already names the file or symbol to change, go straight there:\n  `trail grep \"\u003Csymbol>\"` for the exact `file:line`, then edit. Reserve\n  `trail ask` for when you don't yet know where the code lives — an `ask`\n  round-trip is wasted on a target you can already name.\n- Trust the answer and act. Reach for a second tool only when the first genuinely\n  fell short: weak hits, a truncated span, or a need to be exhaustive.\n- If trail names a path that isn't on disk, its index is ahead of your checkout\n  (a branch switch or unpulled move). Don't read the missing file — `trail grep`\n  the symbol to find where it lives now, or run `trail build` to refresh.\n\n## Report what trail saved, every turn\nEach retrieval tool **opens** its output with a tokens-saved line (`[trail] tokens\nsaved ≈ N` on trail-era binaries; graft-era versions print the same line with a\n`[graft]` prefix): the estimated tokens that call saved versus reading the files it\ncovers whole. Whenever you used any trail tool in a turn, close your reply with a\none-line tally summing those numbers across every call you made, e.g.\n`🌱 trail saved ~12,400 tokens this turn (3 calls)`. A call with no such line\n(tiny files, where the pointers cost as much as the source) saved nothing, so\nskip it. This is the per-turn figure; the statusline carries the running\nsession total.\n\nOnce a turn has been billed, each line also states what that call was worth in\ndollars, at the rate this session is actually paying for input tokens — include\nthat total alongside the tokens, e.g. `🌱 trail saved ~12,400 tokens (~$0.04)\nthis turn`. When a line carries no dollar figure, report tokens alone rather\nthan pricing them yourself.\n\n**Never pipe a trail command through `head`, `tail`, or `sed -n`.** Every tool\nis already capped and states what it dropped; clipping it costs you hits you\nasked for, and it silently drops the savings line the statusline's running\ntotal is parsed from.\n\n## When trail isn't enough\n- Span truncated (\"+N more lines\"): open the file at that exact range.\n- A node lacks a detail: ask a more specific question; only then read source at\n  the exact `file:line`, never a whole file to rebuild understanding trail gives.\n- You may also grep \u002F ls \u002F cat inside the index directory directly (plain\n  markdown; `INDEX.md` indexes the nodes), but the tools above are faster and\n  exhaustive where it matters, so reach for them first.\n\nWhen the tool's MCP server is connected, these are exposed as tools too\n(trail-era names: `trail_*`; graft-era installs expose the `graft_*` spellings —\n`graft_find_code`, `graft_find_all`, `graft_file_api`, `graft_trace_calls` (with\n`direction` \u002F `depth`), `graft_repo_map`, `graft_check_freshness`). Use whichever surface is\navailable; the guidance is identical.\n\n## Learnings notes (`.trail\u002Flearnings\u002F`)\n\nOne file per learning someone asked their agent to save, kept next to the code\nso the next session starts from it (vendor commit-once doctrine —\n`.trail\u002FREADME.md`). The session-start hook (`.trail\u002Fhook.cjs`, registered in\n`.claude\u002Fsettings.json`) injects the live notes as context on every session —\n**including machines without trail installed** (the hook's fallback mode), so\na hand-written note works identically to a tool-written one.\n\n**Naming**: `YYYY-MM-DD-\u003Cslug>-\u003Cauthor>.md` (e.g.\n`2026-10-31-open-bug-tracked-as-ticket-t-sunghyuk.md`). The date prefix is\nload-bearing — the hook derives a note's date from it when front matter omits\n`date`.\n\n**Front matter** (the contract the hook's `liveFiles` parser reads —\n`.trail\u002Fhook.cjs`):\n\n| Field | Contract |\n|---|---|\n| `title` | one-line summary shown in the injected list |\n| `author` | who the learning is credited to |\n| `date` | `YYYY-MM-DD` (falls back to the filename prefix) |\n| `id` | `l-` + 6–16 lowercase hex; the stable identity `replaces` chains point at |\n| `scope` | `repo` |\n| `status` | `active` (injected) \\| `held` (parked) \\| `replaced` \\| `retired` (not injected) |\n| `touches` | repo paths the learning bears on |\n| `replaces` | optional `l-…` id of the note this one supersedes |\n\n**Body**: `## Decided` (with an inline **Why:** line) and `## Watch out`;\nshort summaries, never transcripts (`.trail\u002FREADME.md`); cite ticket ids,\ndesign paths, and memory blocks instead of restating them; end with a\none-line attribution.\n\n**Read\u002Fcredit protocol** (the hook's own injected instruction): read the ones\nthat bear on the task before exploring; when one shapes the reply, credit its\nauthor and what it let you skip. You never edit a learning — corrections are\na NEW note with `replaces: \u003Cold id>`; only `status: active` notes are\ninjected, so retirement is a write, not an edit.\n\n**vs `memory\u002F`** (workspace root): `memory\u002F` is the L0 session-log audit trail\n(agent-authored, PM workflow record). Learnings are per-repo distilled\ntechnical knowledge for the next session (human-attributed, git-tracked,\nauto-injected at session start). Dedupe rule: a learning DISTILLS — it cites\ntickets\u002Fdesigns\u002Fmemory and never duplicates a transcript; overlap between the\ntwo surfaces is complementary by design, not drift.\n\n## Maintenance (workspace)\nThis skill lives in the `skills\u002F` SSOT (`skills\u002Ftrail\u002FSKILL.md` — renamed from\n`skills\u002Fgraft\u002F` per design 2026-10-31-graft-trail-migration, U-20261031-009). Its\nplatform mirrors and helper files are SELF-MANAGED by the tool CLI\n(docs\u002Fself-managed-surfaces.json, design 2026-10-02-self-managed-tool-surfaces):\nsync-skills does not mirror them, and git ignores them. After upgrading the tool\n(`trail upgrade`), run `trail init` in the repo to refresh those surfaces (graft-era\nbinaries: `graft init`); keep this SSOT copy frontmatter valid (lifecycle gates\nread it).\n","# trail\n\n> **Alias note**: renamed from graft (vendor rename 0.28, `@trailhq\u002Ftrail-code`);\n> `graft …` commands in older references read as `trail …`. On repos not yet\n> migrated the binary and index still carry their pre-rename names (`graft`,\n> `graft\u002F`) — same tools, same flags; run the pre-rename spelling there, or run\n> the vendor upgrade first (`trail upgrade` auto-runs `trail init` and rewrites\n> the repo surfaces to trail-era naming).\n\nThe trail index holds a graph of this repo: small markdown nodes that each explain\none part in prose and name the exact `file:line` spans they cover, plus a wiring\ngraph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding\nthat understanding by reading source costs thousands, and misses the edges.\n\nEvery command below is `$0`, needs no API key, and returns in under a second.\nThere are six of them. **Pick the one that fits the task, run it, act on the\nanswer; don't chain tools hoping for more. Most tasks need one call.**\n\n## The tools\n\n### 1 · `trail ask \"\u003Cquestion>\" --source`: locate + understand (the default)\nRanked retrieval over the graph, routed automatically between prose nodes and\nthe wiring graph, returning the top hits with exact `file:line`.\n- `--source` inlines the code at each hit, the ≤8-line **crux** of each\n  definition, so the result IS the code you need, no follow-up file read. Add\n  `--full` only when the crux is too small to act on.\n- `--in \u003Cpath>` narrows to a subtree before ranking; `-n N` caps results (default 8).\n- **Use it when** the question is conceptual or locational: \"how does auth\n  work\", \"where is rate-limiting handled\", \"what assembles the request pipeline\".\n- One ask usually answers. A genuinely multi-part question needs one ask per\n  distinct sub-aspect, never the same question reworded. Few or weak hits mean\n  switch tool (grep \u002F skeleton \u002F callers), don't re-ask.\n\n### 2 · `trail grep \"\u003Cpattern>\"`: exhaustive find\nRegex (or `--fixed` for a literal) over every indexed file, hits **grouped by\nenclosing symbol** and ranked by coupling; it also reports files it couldn't read.\n- **Use it when** you need every occurrence: all call sites, all uses of a\n  constant, all providers. `ask` is ranked top-N and *will* miss instances;\n  grep won't. One grep replaces a spray of asks.\n- Search a **short symbol name or literal**, not a full guessed signature: an\n  over-specific regex (`func (s *Server) GenerateHandler`) returns nothing even\n  when the code is indexed. If a grep misses, **loosen it** (drop the receiver\n  and signature, keep the bare name) and retry `trail grep` — do NOT switch to\n  raw `grep -rn`, which is slower and unranked.\n- `-i` case-insensitive; `--in \u003Cpath>` scopes to a subtree. Raw `grep -rn` is\n  only for files trail genuinely doesn't index (docs, configs, brand-new files).\n\n### 3 · `trail skeleton \u003Cfile>`: a file's API at a glance\nSignatures-only view of one file (every function \u002F method \u002F type with its span)\nin ~200 tokens, ~10x cheaper than reading the file.\n- **Use it when** you need \"what's in this file \u002F what can I call here\" before\n  editing or wiring into it. One skeleton is the whole answer for a file; don't\n  re-skeleton the same file, and don't skeleton every file `map` already named.\n\n### 4 · `trail callers \u003Csymbol>`: the exact edges\nPrecomputed call\u002Freference edges, not a text search. Symbol can be bare\n(`Foo`), qualified (`Class.method`), or package-qualified (`pkg.Fn`).\n- default `--direction in`: **who calls\u002Freferences** this; run before you\n  rename, delete, or change its signature.\n- `--direction out`: **what this symbol itself calls\u002Fdepends on** (the old `callees`).\n- `--depth N`: walk transitively N hops for the **full blast radius** (the old\n  `impact`); `--depth 2` is the usual \"what breaks if I touch this\".\n- `--depth all`: the **entire connected closure** — every source reachable\n  through the edges. Reach for this before a **refactor, rename, or any\n  multi-file change**: it surfaces the sibling and downstream files (platform\n  variants, a module you must split out) that a single-file edit would miss.\n\n### 5 · `trail map`: orientation for an unfamiliar repo or area\nA token-budgeted tour: directory clusters, per-directory hubs, and global\nhotspots, straight from the wiring graph.\n- **Use it when** you land in a repo cold or are asked for \"the architecture\".\n  `map` alone is the answer: read the hub cards it names; do NOT then skeleton\n  or ask your way through every subsystem it lists. `--max-dirs N` widens it.\n\n### 6 · Lifecycle: `trail build` \u002F `trail check`\nEvery tool above refreshes the graph itself before answering, so what those tools\nreturn always describes the code as it is right now — including edits you just made\nand have not committed. You do **not** need to run `build` after editing.\n\n**The AGENTS.md trail block is tool-managed** (verified 2026-10-04, T-20261004-001,\ngraft-era mechanics; trail-era rewrites keep the same behavior):\nthe Claude Code session-start hook runs the tool's upkeep, whose `reconcileWiring`\ntreats a hand-deleted instruction block as accidental loss and re-appends it\n(`upsertSection` on the tool's markers — graft-era installs used\n`graft:start`\u002F`graft:end`; a `trail init` rewrite swaps them for the trail\nequivalents). Hand-editing or withdrawing the block from AGENTS.md is therefore\nundone at the next session start; the durable removal is\n`trail uninstall -y --keep-cache` (graft-era binaries: `graft uninstall`),\nwiring only — keeps the index directory and its cache. The block text lives in\nthe tool package (`hosts\u002Finstructions.js instructionBody()`); this SKILL.md is\nthe doctrine SSOT for tool behavior — the AGENTS.md block is a package-rendered\nsummary.\n\nOne caveat, if you `grep` the markdown under the index directory directly\n(`graft\u002F` pre-rename, `.trail\u002Fcache\u002F` after `trail init`): those cards are a\nprojection, rebuilt at the end of the turn rather than on each query, so after an edit\nthey can lag. The tools above never do — prefer them, and treat a card's spans as\nstale if you have edited that file this turn.\n\n`build` is for the LLM layer (`--deep` adds a concept map; skip unless asked);\n`check` fails when the index is stale, for CI.\n\n## Scenarios: the shortest path through a coding task\n\n| When you're… | Reach for | Calls |\n|---|---|---|\n| Onboarding \u002F \"explain this codebase\" | `trail map`, then read the named hub cards | 1 |\n| Understanding a flow (\"how does X work\") | `trail ask \"\u003Cflow>\" --source` | 1 |\n| Finding where a change belongs | `trail ask \"where is \u003Cbehavior>\" --source` | 1 |\n| Editing a symbol you can already name | `trail grep \"\u003Csymbol>\"`, edit at the `file:line` (skip `ask` — you know where it is) | 1 |\n| Renaming \u002F deleting \u002F changing a signature | `trail callers \u003Csym> --depth 2` first | 1 |\n| Refactor \u002F multi-file change (before editing) | `trail callers \u003Csym> --depth all` — map every connected file, don't stop at the first | 1 |\n| \"What does this depend on?\" | `trail callers \u003Csym> --direction out` | 1 |\n| Finding every occurrence of a pattern | `trail grep \"\u003Cliteral>\"` | 1 |\n| \"What's the API of this file?\" | `trail skeleton \u003Cfile>` | 1 |\n| Debugging a failure in area X | `trail ask \"\u003Csymptom>\" --source`, then `callers` on the suspect | 1–2 |\n| Judging a diff's risk before merge | `trail callers \u003Cchanged sym> --depth 2` | 1 \u002F symbol |\n| Working inside one repo of a monorepo | add `--in \u003Cscope>\u002F` to ask \u002F grep \u002F callers | n\u002Fa |\n\nIn a multi-repo workspace, trail ranks fairly so the biggest repo can't drown\nthe rest, and every hit carries a `[scope\u002F]` label naming its sub-project; when\nyou already know where you're working, narrow with `trail ask \"\u003Ctask>\" --in \u003Cscope>\u002F`.\n\n## Spend the fewest calls\n- A node's `covers:` list already gives exact `file:line` for every symbol, so\n  cite straight from it. The spans are generated from source and authoritative;\n  don't re-open or re-grep files to \"double-check\".\n- When the task already names the file or symbol to change, go straight there:\n  `trail grep \"\u003Csymbol>\"` for the exact `file:line`, then edit. Reserve\n  `trail ask` for when you don't yet know where the code lives — an `ask`\n  round-trip is wasted on a target you can already name.\n- Trust the answer and act. Reach for a second tool only when the first genuinely\n  fell short: weak hits, a truncated span, or a need to be exhaustive.\n- If trail names a path that isn't on disk, its index is ahead of your checkout\n  (a branch switch or unpulled move). Don't read the missing file — `trail grep`\n  the symbol to find where it lives now, or run `trail build` to refresh.\n\n## Report what trail saved, every turn\nEach retrieval tool **opens** its output with a tokens-saved line (`[trail] tokens\nsaved ≈ N` on trail-era binaries; graft-era versions print the same line with a\n`[graft]` prefix): the estimated tokens that call saved versus reading the files it\ncovers whole. Whenever you used any trail tool in a turn, close your reply with a\none-line tally summing those numbers across every call you made, e.g.\n`🌱 trail saved ~12,400 tokens this turn (3 calls)`. A call with no such line\n(tiny files, where the pointers cost as much as the source) saved nothing, so\nskip it. This is the per-turn figure; the statusline carries the running\nsession total.\n\nOnce a turn has been billed, each line also states what that call was worth in\ndollars, at the rate this session is actually paying for input tokens — include\nthat total alongside the tokens, e.g. `🌱 trail saved ~12,400 tokens (~$0.04)\nthis turn`. When a line carries no dollar figure, report tokens alone rather\nthan pricing them yourself.\n\n**Never pipe a trail command through `head`, `tail`, or `sed -n`.** Every tool\nis already capped and states what it dropped; clipping it costs you hits you\nasked for, and it silently drops the savings line the statusline's running\ntotal is parsed from.\n\n## When trail isn't enough\n- Span truncated (\"+N more lines\"): open the file at that exact range.\n- A node lacks a detail: ask a more specific question; only then read source at\n  the exact `file:line`, never a whole file to rebuild understanding trail gives.\n- You may also grep \u002F ls \u002F cat inside the index directory directly (plain\n  markdown; `INDEX.md` indexes the nodes), but the tools above are faster and\n  exhaustive where it matters, so reach for them first.\n\nWhen the tool's MCP server is connected, these are exposed as tools too\n(trail-era names: `trail_*`; graft-era installs expose the `graft_*` spellings —\n`graft_find_code`, `graft_find_all`, `graft_file_api`, `graft_trace_calls` (with\n`direction` \u002F `depth`), `graft_repo_map`, `graft_check_freshness`). Use whichever surface is\navailable; the guidance is identical.\n\n## Learnings notes (`.trail\u002Flearnings\u002F`)\n\nOne file per learning someone asked their agent to save, kept next to the code\nso the next session starts from it (vendor commit-once doctrine —\n`.trail\u002FREADME.md`). The session-start hook (`.trail\u002Fhook.cjs`, registered in\n`.claude\u002Fsettings.json`) injects the live notes as context on every session —\n**including machines without trail installed** (the hook's fallback mode), so\na hand-written note works identically to a tool-written one.\n\n**Naming**: `YYYY-MM-DD-\u003Cslug>-\u003Cauthor>.md` (e.g.\n`2026-10-31-open-bug-tracked-as-ticket-t-sunghyuk.md`). The date prefix is\nload-bearing — the hook derives a note's date from it when front matter omits\n`date`.\n\n**Front matter** (the contract the hook's `liveFiles` parser reads —\n`.trail\u002Fhook.cjs`):\n\n| Field | Contract |\n|---|---|\n| `title` | one-line summary shown in the injected list |\n| `author` | who the learning is credited to |\n| `date` | `YYYY-MM-DD` (falls back to the filename prefix) |\n| `id` | `l-` + 6–16 lowercase hex; the stable identity `replaces` chains point at |\n| `scope` | `repo` |\n| `status` | `active` (injected) \\| `held` (parked) \\| `replaced` \\| `retired` (not injected) |\n| `touches` | repo paths the learning bears on |\n| `replaces` | optional `l-…` id of the note this one supersedes |\n\n**Body**: `## Decided` (with an inline **Why:** line) and `## Watch out`;\nshort summaries, never transcripts (`.trail\u002FREADME.md`); cite ticket ids,\ndesign paths, and memory blocks instead of restating them; end with a\none-line attribution.\n\n**Read\u002Fcredit protocol** (the hook's own injected instruction): read the ones\nthat bear on the task before exploring; when one shapes the reply, credit its\nauthor and what it let you skip. You never edit a learning — corrections are\na NEW note with `replaces: \u003Cold id>`; only `status: active` notes are\ninjected, so retirement is a write, not an edit.\n\n**vs `memory\u002F`** (workspace root): `memory\u002F` is the L0 session-log audit trail\n(agent-authored, PM workflow record). Learnings are per-repo distilled\ntechnical knowledge for the next session (human-attributed, git-tracked,\nauto-injected at session start). Dedupe rule: a learning DISTILLS — it cites\ntickets\u002Fdesigns\u002Fmemory and never duplicates a transcript; overlap between the\ntwo surfaces is complementary by design, not drift.\n\n## Maintenance (workspace)\nThis skill lives in the `skills\u002F` SSOT (`skills\u002Ftrail\u002FSKILL.md` — renamed from\n`skills\u002Fgraft\u002F` per design 2026-10-31-graft-trail-migration, U-20261031-009). Its\nplatform mirrors and helper files are SELF-MANAGED by the tool CLI\n(docs\u002Fself-managed-surfaces.json, design 2026-10-02-self-managed-tool-surfaces):\nsync-skills does not mirror them, and git ignores them. After upgrading the tool\n(`trail upgrade`), run `trail init` in the repo to refresh those surfaces (graft-era\nbinaries: `graft init`); keep this SSOT copy frontmatter valid (lifecycle gates\nread it).\n",{"name":5,"owner":23,"scope":24,"mirror":19,"status":25,"version":26,"metadata":27,"description":35,"l2_propagate":19,"last_reviewed":36,"prerequisites":37},"pm","common","active","1.2.0",{"type":28,"triggers":29},"process",[5,30,31,32,33,34],"graft","repo context graph","find where code lives","what calls this symbol","blast radius","This repo is indexed by the trail repo-context-graph. For ANY task here, whether understanding how something works, finding where code lives, tracing what calls a symbol or what a change breaks, or scoping an edit, get your context from trail before grepping or reading source files.\n",1794096000000,"trail CLI","main","1162ccc568cf90c01b3886d6143cbfd851a37883","skills\u002Ftrail",9,"https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards","https:\u002F\u002Fgithub.com\u002F5throck","Experienced in digital transformation, enterprise IT, startup acceleration, and business strategy. Focused on building practical systems that connect technolo","2026-11-14 21:22:34",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":58},[48,51,54],{"tool":49,"command":50},"npx","npx skills add 5throck\u002Fai-workspace-standards --skill trail",{"tool":52,"command":53},"bunx","bunx skills add 5throck\u002Fai-workspace-standards --skill trail",{"tool":55,"command":56},"pnpm","pnpm dlx skills add 5throck\u002Fai-workspace-standards --skill trail","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Fskills\u002Ftrail\u002FSKILL.md",true,[],[61,69,74,79,84,89],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":68},"01M7BBJDYHJMGTJYSC37JVWY8S","i18n-layout","Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL\u002Fbidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF\u002FBOM issues surface.","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":70,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":68},"01M7BBJ9XHAAS1AVGKZZ841VBZ","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.hermes\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":75,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":68},"01M7BBJ5C3X8TKFKG5R9P9P49W","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.gemini\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":80,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":68},"01M7BBJ1B52X0QMJ2QVBMPJB37","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.codex\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":85,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":68},"01M7BBHX91BW2Q2R276MRX5AW3","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.claude\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":90,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":68},"01M7BBHQWGXPSFRWN1PRC2NMMV","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.agents\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[]]