The machine now carries its own manual for AI hands

Claude-Session: https://claude.ai/code/session_01Ms2FbjQy31TVf3CEvQhGM8

user/README.md

@@ -13,13 +13,37 @@ and one file says where each piece goes.
 | 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` | Linked as a directory, so a skill installed on any machine lands in the checkout. |
+| `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

user/manifest

@@ -7,6 +7,10 @@
 #          repository. Use this for anything you want to update once and have
 #          change everywhere -- and for anything a tool writes into, because a
 #          skill installed on this machine should land in the checkout.
+#   linkdir  symlink each child of the source into the destination, which is
+#          created as a real directory. Use this where the destination holds
+#          more than this one source -- ~/.claude/skills also carries Panama's
+#          own shipped skills -- so it cannot be a symlink to any single place.
 #   copy   copy once, and never touch it again if the destination exists. Use
 #          this for files a machine legitimately diverges on.
 #
@@ -24,11 +28,15 @@
 link  agents/AGENTS.md   ~/.claude/CLAUDE.md
 link  agents/AGENTS.md   ~/.codex/AGENTS.md
 
-# Skills, at both paths that look for them. Linked as whole directories rather
-# than file by file, so a skill installed by any tool lands in the checkout and
-# `panama update` offers to commit it.
-link  agents/skills      ~/.agents/skills
-link  agents/skills      ~/.claude/skills
+# Skills, at both paths that look for them. Linked so that a skill installed by
+# any tool lands in the checkout and `panama update` offers to commit it.
+#
+# ~/.agents/skills is this directory and nothing else, so it stays one link.
+# ~/.claude/skills also holds the skills Panama itself ships, put there by the
+# link-skills stage, so it is a real directory with one link per skill -- and
+# this stage runs after that one, so a personal skill wins a name collision.
+link     agents/skills   ~/.agents/skills
+linkdir  agents/skills   ~/.claude/skills
 
 link  agents/rules       ~/.claude/rules