Keep the personal half of the desktop in one place, and ask before installing it

Agent instructions, skills, SSH host aliases and expansion triggers are worth
having identical on every machine one person owns, and belong in none of the
shared configuration. They live in user/ now, with a manifest saying where each
piece goes and a link-user stage that puts it there.

That stage does nothing unless the machine said yes. Somebody who clones Panama
to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was;
the question names the destinations and defaults to no. Anything displaced goes
to config/old rather than being deleted.

~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one
file, which is the drift this exists to prevent.

Also adds the vitals toggles for the battery and Claude usage readouts, which
had preferences and no way to reach them.

user/agents/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: writing-for-agents
+description: Use when creating or editing a skill, CLAUDE.md, AGENTS.md, or any document an agent reads through a pointer; also when a skill fires unreliably, gets skipped mid-run, or has grown too long to trust.
+---
+
+# Writing for Agents
+
+The reference for any document an agent consumes: a skill, a `CLAUDE.md`, a doc reached by a
+pointer. The packaging differs; the writing does not. The same levers make each one predictable,
+because the agent takes the same *process* every run rather than producing the same output.
+
+When the document is a skill, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md) for frontmatter,
+invocation, and routers.
+
+## Start from the failure
+
+Name the failure you are fixing before writing a line. The form that fixes one kind measurably
+backfires on another.
+
+| Baseline failure | Form that fixes it | Form that backfires |
+|---|---|---|
+| Knows the rule, skips it under pressure | Prohibition + rationalization table + red flags | Soft guidance ("prefer", "consider") |
+| Complies, but the output is the wrong shape (bloated, buried verdict, restated spec) | Positive recipe: state what the output **is**, its parts, in order | Prohibition list ("don't restate", "never narrate") |
+| Omits a required element from something it already produces | Structural: a REQUIRED slot in the template it fills in | Prose reminders near the template |
+| Behavior should depend on a condition | Conditional on an observable predicate ("if the brief exists, reference it") | Unconditional rule plus exemption clauses |
+
+Under a competing incentive, an agent negotiates with "don't X". A recipe leaves nothing to
+negotiate: the output matches the stated shape or it does not.
+
+Two rules bind whichever form you pick:
+
+- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation. Express a real
+  exception as its own conditional on an observable predicate.
+- **Exemption clauses do not scope.** "This limit does not apply to code blocks" still suppresses
+  code blocks. If part of the output must be exempt, restructure so the rule cannot reach it.
+
+## Prompt the positive
+
+Negation is the failure mode beside every lever here. Steering by prohibition drags the forbidden
+behavior into context and makes it *more* available, not less. *Don't think of an elephant*, and the
+elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns,
+so the ban half-reads as an instruction to do the thing.
+
+State the target behavior instead, so the banned one is never spoken. A prohibition earns its place
+only in row one of the table above, a discipline failure you cannot phrase positively, and even
+there it pairs with the positive target so attention lands on what to do.
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent
+thinks with while running the document: *tight*, *red*, *seam*, *tracer bullet*, *fog of war*.
+Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a
+whole region of behavior in the fewest tokens, by recruiting priors the model already holds.
+
+It anchors twice. In the body, *execution*: the agent reaches for the same behavior every time the
+word appears. In a pointer, *invocation*: when the same word lives in your prompts, your docs, and
+your codebase, the agent links that shared language to the material and reaches it more reliably.
+
+Coining your own works if you define it clearly, but a made-up word recruits no priors: you pay in
+definition tokens what a pretrained word gives free. Reach for an existing word first.
+
+Hunt for the refactor. A triad spelled out at three sites, or a pointer spending a sentence to
+gesture at one idea, is a passage begging to collapse into a single token:
+
+- "fast, deterministic, low-overhead" becomes *tight* (a *tight* loop).
+- "a loop you believe in" becomes *red*, turning a fuzzy gate into a binary observable state.
+
+Assume every document is carrying restatements that leading words retire. Go find them.
+
+## Context pointers
+
+A **context pointer** is a reference held in the agent's context that names some out-of-context
+material and encodes the condition for reaching it. A skill's description is one; a line in
+`CLAUDE.md` naming a doc is the same object. The pointer's *wording*, not its target, decides when
+the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer
+is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs: name what the material is, and list the **branches** that should trigger
+reaching it (a branch is a distinct case the document handles, so different runs take different
+paths through it). Every word of an always-loaded pointer costs on every turn, so it earns harder
+pruning than the body:
+
+- **Front-load the leading word.** The pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice.
+- **Cut identity the body already carries.**
+- **Name the material, never its process.** A pointer that summarizes the workflow becomes a
+  shortcut the agent takes *instead of* reading the body: a description saying "review between
+  tasks" produced one review where the body specified two. Name what the document covers and when
+  to reach it; let the body own the steps.
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** is the cost of always-loaded material on the agent's window: a `CLAUDE.md` line,
+  a skill description, anything sitting in context every turn, spending tokens and attention whether
+  or not it fires.
+- **Cognitive load** is the cost on you: which documents exist and when to reach for each. You are
+  the index. Not a cost to minimize; it is the price of your own agency. Spend it where your
+  judgment matters, remove it where it does not.
+
+Material reached only through a pointer escapes context load at the price of the pointer's own line.
+Material with no pointer at all rides entirely on cognitive load.
+
+## Information hierarchy
+
+A document is built from two content types: **steps** (the ordered actions the agent performs) and
+**reference** (definitions, rules, facts consulted on demand). The two mix freely: all steps, all
+reference, or both. The core decision is where each piece sits on the ladder, ranked by how
+immediately the agent needs it:
+
+1. **In-file step**: the primary tier, what the agent does, in order.
+2. **In-file reference**: consulted on demand. Often a legitimately flat peer-set (every rule of a
+   review on one rung), which is a fine arrangement, not a smell.
+3. **Disclosed reference**: pushed into a separate file behind a pointer, loaded only when the
+   pointer fires.
+
+Push too little down and the top bloats; push too much and you hide material the agent needs. That
+tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder so the top stays legible. Not primarily a
+token optimization: it is how the hierarchy is protected. **Branching is the test**: inline what
+every branch needs, and disclose what only some branches reach. In a document with steps, in-file
+reference that should be disclosed buries them and turns attending to them into a coin-flip.
+
+**Co-location** is the within-file companion. The ladder decides how far down a piece sits;
+co-location decides what sits beside it once there. Keep a concept's definition, rules, and caveats
+under one heading rather than scattered, so reading one part brings its neighbors with it. The test:
+the document should read like documentation written for the agent.
+
+**Sprawl** is the failure mode here: a document simply too long, even when every line is live and
+unique. Attention thins across the excess, and every extra line is one more to keep relevant. The
+cure is the ladder.
+
+## Completion criteria
+
+Every step ends on a **completion criterion**, the condition that tells the agent the work is done.
+Two properties make it a lever:
+
+- **Clarity**: can the agent tell done from not-done? A vague bound ("understanding reached")
+  invites **premature completion**, ending the step before it is genuinely done, attention slipping
+  to *being done*. The visible steps still ahead supply the pull; the criterion's clarity is the
+  resistance. Defend in order: sharpen the bound first, since that is local and cheap; only if it is
+  irreducibly fuzzy *and* you observe the rush, split the sequence to hide the later steps. Hiding
+  works only across a real context boundary, a handoff or a subagent dispatch. An inline call leaves
+  the later steps in context and clears nothing.
+- **Demand**: how much it requires. "Every modified model accounted for" forces thorough work where
+  "produce a change list" does not. Demand drives the digging the agent does within the work, and it
+  is not step-bound: "every rule applied" binds a body of flat reference just as "every step done"
+  binds a sequence.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By branch**: the disclosure test above. The most common correct cut.
+- **By sequence**: split a run of steps where the later steps tempt the agent to rush the one in
+  front of it. Beware the reverse: merging sequences exposes each step to what follows, inviting
+  premature completion.
+- **By invocation**: skill-specific, see [SKILL-MECHANICS.md](SKILL-MECHANICS.md).
+
+## Pruning
+
+- **Single source of truth.** One authoritative place per meaning, so changing the behavior is a
+  one-place edit. **Duplication** costs maintenance and tokens, and inflates a meaning's prominence
+  on the ladder past its real rank. It is the accidental inverse of a leading word, which repeats a
+  token on purpose, never the meaning.
+- **The environment is a source of truth too.** `package.json` scripts, config files, the directory
+  layout, `--help` output. A document that restates it is a **cache**: a copy of a lookup, earning
+  its load only when the lookup is expensive. Cache what the agent cannot find by looking, such as
+  the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the
+  one-command lookups to the environment, where they cannot go stale.
+- **Relevance.** Does the line still bear on what the document does? A line loses relevance by never
+  bearing on the task, or by going stale as the world it describes changes. Without a pruning
+  discipline the default fate is **sediment**: stale layers that settle because adding feels safe
+  and removing feels risky, until you must core down through them to find what is still live.
+- **No-ops.** An instruction the model already obeys by default pays load to say nothing. The test
+  (does it change behavior versus the default?) is model-relative, not reader-relative: two people
+  disagreeing about a no-op disagree about the default, and settle it by running the document, not
+  by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The
+  test also grades leading words: a word too weak to beat the default (*be thorough*, when the agent
+  is already thorough-ish) is a no-op, and the fix is a stronger word (*relentless*), not a
+  different technique.
+
+## House conventions
+
+- **One excellent example beats five mediocre ones.** Write it in the language the document actually
+  targets: TypeScript for application work, shell for infra. A complete, runnable, commented example
+  from a real scenario, not a fill-in-the-blank template.
+- **Name for what it does**, verb-first. Gerunds suit processes: `writing-for-agents`,
+  `diagnosing-bugs`. Not `agent-doc-guidelines`.
+- **No narrative.** "In the session where we found the Convex race condition" is not reusable. State
+  the technique.
+- **Keep the document in sync with what it describes.** A document naming a script, flag, or path
+  owes the same upkeep as the code it names. A stale pointer is worse than no pointer, because the
+  agent follows it.
+- **Supporting files only for a reusable tool or heavy reference.** A script, a template, or a
+  branch too large to inline. Principles and short patterns stay in the main file.
+
+## Verifying
+
+Scale the check to what the document does. Reference gets read back; discipline gets tested.
+
+| The document is | Verify by |
+|---|---|
+| Pure reference (a vocabulary, an API guide) | Reading it back against the ladder and the pruning rules |
+| A procedure you run yourself | Running it once on a real task; where it stalls is the bug |
+| Behavior-shaping guidance: a rule expected to hold under pressure, or wording meant to change output shape | Baselining it first. Read [VERIFYING.md](VERIFYING.md) |
+
+## Done when
+
+- The failure being fixed is named, and the form matches its row in the table.
+- Every rule is phrased as a positive target, except a discipline prohibition that cannot be.
+- Each branch is inlined or disclosed on purpose, and the pointer to each disclosed file names its
+  material and its trigger.
+- Every step carries a completion criterion that is checkable and exhaustive.
+- No line restates the environment, duplicates a meaning, or fails the no-op test.
+- The document is shorter than the material it replaced.