76 lines
3.5 KiB
Markdown
76 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
./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.
|