Panama/user

Personal content

Everything else in Panama is the desktop. This directory is the person using it.

The problem it solves is small and annoying: an agent skill, an SSH host alias or a set of expansion triggers is worth having on every machine you own, but none of it belongs in the shared configuration, and keeping it in a second repository means remembering to update two things. So it lives here, tracked, and one file says where each piece goes.

What is in here

Path	Goes to	Why
agents/AGENTS.md	~/.claude/CLAUDE.md, ~/.codex/AGENTS.md	Two tools, two names, one file. These were byte-identical copies before this, waiting to disagree.
agents/skills/	~/.agents/skills, ~/.claude/skills	A skill installed on any machine lands in the checkout. The Claude path is linkdir — see below.
agents/rules/	~/.claude/rules
ssh/config	~/.ssh/config	Host aliases only. Keys are per-machine and are never tracked.
espanso/identity.yml	~/.config/espanso/match/identity.yml	Copied, not linked, because a machine may add its own triggers.

manifest is the authority; this table is a summary of it.

The three kinds

link and copy mean what they say: one symlink, or one copy made only if the destination is empty. linkdir is the third, and it exists because one destination is no longer only ours.

Panama ships its own agent skills now (skills/, linked by setup/scripts/link-skills), and they go to ~/.claude/skills — the same directory the personal ones went to as a single symlink. A directory cannot be a symlink to two places, so that entry became linkdir: the destination is a real directory, and each child of user/agents/skills/ is linked into it individually. ~/.agents/skills is still a whole-directory link, because nothing else claims it.

Two consequences, recorded rather than fixed:

• A personal skill named like a shipped one shadows it. link-user runs after link-skills and displaces what it finds, so the personal one wins. That is the intent, and it is the precedence Claude Code uses anyway.
• A new personal skill needs a re-link to appear. The whole-directory link showed a newly created skill instantly; per-child links do not know about a child that did not exist when they were made. Run panama update or setup/scripts/link-user after adding one.

It is off unless you say yes

The installer asks, naming the destinations, and the default is no. Nothing here is linked on a machine that did not answer yes, and the answer is remembered in $XDG_STATE_HOME/panama/user-content so upgrades do not re-ask.

That gating is the whole reason this can be tracked in a repository other people clone. If you are that other person: delete what is in here, put your own in its place, and answer yes. The mechanism is yours, the contents are not.

Adding something

Put the file under user/, add a line to manifest, run:

./setup/scripts/link-user

Anything already at the destination is moved to config/old/ rather than deleted, under a name that says where it came from.

What does not go in here

Anything secret. This repository is readable by anyone who finds it, and the contract test refuses private keys, tokens and credentials outright. That means no ~/.ssh/id_*, no .credentials.json, no API keys, and no settings.json carrying the names of hosts or people you would rather not publish. Machine state that a tool rewrites on its own does not belong here either; it will churn the git history for no benefit.