lshed 0.3.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.6.0 — 2026-09-03
+
+- `lshed sync [-m <msg>] [--no-push] [--dry-run]`: commits everything in the shed, `git pull --rebase`, `git push` (setting the upstream the first time). Without `origin` it only commits. When commits come in it says to run `lshed restore`. On a conflict it aborts the rebase, leaves your commit in place and hands you the git command. It warns first if `diff` shows edits you have not saved, and never runs `save` for you.
+- README rewritten as a usage guide: day one, daily loop, new machine, profiles, adding things, updating packages, housekeeping, output marks, every command with its flags.
+
+## 0.5.0 — 2026-09-03
+
+`init` was a one-shot. Anything you made afterwards had to be copied into the shed and typed into `lshed.yaml` by hand.
+
+- `lshed add [keys...] [--all]` scans the agent root the way `init` does and lists what the shed lacks: authored skills, agents, commands, MCP servers, and git clones or plugins that should be packages. Without keys it only lists. Chosen items are copied (or recorded with a lock entry for packages), appended to `lshed.yaml` with your comments intact, added to the current profile, and added to the managed set.
+- `status` reports things outside the shed as `창고 밖 N개 → lshed add`.
+- `init --exclude` is now remembered as `exclude:` in the manifest, so `add` and `status` do not keep proposing the aliases you left out.
+- `init` and `add` share one classification path (`discover`) and one ingest path, so they cannot drift apart. `init` now edits a YAML document instead of serialising an object; output is unchanged.
+
+## 0.4.0 — 2026-09-03
+
+Hand-configured MCP servers travel with the profile. Secret values do not.
+
+- New category `mcp` for Claude Code: each user-scope server in `~/.claude.json` becomes `mcp/<name>.json` in the shed. `restore` writes only `mcpServers.<name>` and leaves the rest of the file (machine ID, session state, servers you added by hand) untouched. The file is replaced atomically.
+- `init` masks values under `env` and `headers` whose key looks like a secret with `${VAR}` (`EXA_API_KEY` → `${EXA_API_KEY}`, `Authorization: Bearer …` → `Bearer ${NOTION_AUTHORIZATION}`). Claude Code expands `${VAR}` from the environment in every scope, so `restore` places the placeholder verbatim and no secret passes through lshed. Verified against the real binary.
+- `restore` and `status` list the variables a profile needs that are not set in the current shell.
+- `diff` shows entry changes by key path; `save` keeps placeholders that still match and masks newly added secret-looking keys.
+- Profile switches remove only the servers lshed placed, backing each up as JSON.
+- Adapter interface: `entries()` returns categories that live as JSON entries instead of files, with `secretKeys` and `expandsEnv` policy. The default root honours `CLAUDE_CONFIG_DIR`.
+- Managed-set paths for entries are written as `mcp:<name>`; a colon cannot appear in a path segment, so they never collide with files.
+
 ## 0.3.0 — 2026-09-02
 
 Claude Code plugins are packages now. On the machine this was built against, the five installed plugins were the only thing a fresh `restore` still left out, and two of them carry MCP servers.

package/README.md

@@ -1,13 +1,13 @@
 # lshed
 
-Keep your coding-agent harness — skills, subagents, commands, instructions — in a **shed**, and restore it on any machine with one command.
+Keep your coding-agent harness — skills, subagents, commands, instructions, MCP servers — in a **shed**, and restore it on any machine with one command.
 
 ```
 lshed init --shed ~/lshed          # scan ~/.claude into a shed + write lshed.yaml
 lshed restore research             # apply a profile anywhere
 ```
 
-The shed is a plain directory. Put it in a git repo, Dropbox, whatever. lshed does not sync it for you.
+The shed is a plain directory. Put it in a git repo, Dropbox, whatever. `lshed sync` wraps the git part if you want it to.
 
 ## Why
 
@@ -17,7 +17,7 @@ lshed adds three first-class ideas on top of "a directory in git":
 
 | Idea | What it gives you |
 |---|---|
-| **Components** | every skill / agent / command / instruction fragment is one named part in the shed |
+| **Components** | every skill / agent / command / instruction fragment / MCP server is one named part in the shed |
 | **Profiles** | named recipes — `research`, `work`, `minimal` — that pick a subset of parts |
 | **Managed set** | lshed remembers what it placed, so switching profiles removes only its own files and never touches yours |
 
@@ -29,29 +29,190 @@ Currently supports **Claude Code** (`~/.claude`). Other agents plug in through a
 npm install -g lshed
 ```
 
-Node 20 or newer.
+Node 20 or newer. `git` on the PATH for packages and `sync`. `claude` on the PATH if your shed lists plugins.
 
 ## Quick start
 
 ```bash
 # 1. On the machine that already has your setup
 lshed init --shed ~/lshed
-cd ~/lshed && git init && git add -A && git commit -m "my harness" && git remote add origin <your private repo> && git push -u origin main
+cd ~/lshed && git init && git remote add origin <your private repo>
+lshed sync                                  # commit + push
 
 # 2. Edit ~/lshed/lshed.yaml — add profiles, drop parts you don't need everywhere
 
 # 3. On any other machine
 git clone <your private repo> ~/lshed
-lshed restore research --shed ~/lshed      # --shed only needed the first time
+lshed restore research --shed ~/lshed       # --shed only needed the first time
 ```
 
+## How to use it
+
+### Day one: put what you have into a shed
+
+```
+$ lshed init --shed ~/lshed --exclude _gstack-command connect-chrome
+스캔: /home/me/.claude  →  창고: /home/me/lshed
+  ≡ package gstack  github:garrytan/gstack@main @253d1df  (참조만 기록)
+  ≡ package claude-plugins-official  claude-marketplace:anthropics/claude-plugins-official  (참조만 기록)
+  ≡ package exa  claude-plugin:exa@claude-plugins-official @3.4.1  (참조만 기록)
+  · skills/browse  (gstack 가 생성한 것 → 건너뜀)
+  · skills/review  (gstack 가 생성한 것 → 건너뜀)
+  - skills/_gstack-command  (--exclude)
+  + skills/add-drivers
+  + skills/domain-modeling
+  + mcp/notion  (시크릿 → ${NOTION_AUTHORIZATION})
+  + instructions/main  (CLAUDE.md)
+
+lshed.yaml 생성: /home/me/lshed/lshed.yaml  (부품 4개, 패키지 3개, 생성물 53개 건너뜀, 제외 2개, 프로필 "default")
+```
+
+`init` reads your agent root and writes only to the shed and `~/.claude/lshed/`. It sorts everything into [three kinds](#three-kinds-of-things): authored parts are copied (`+`), things you installed become packages recorded by source and version (`≡`), and files an installer generated are skipped (`·`). Aliases an installer created without symlinks look authored; leave them out with `--exclude`, and lshed remembers that under `exclude:` in the manifest.
+
+Then open `lshed.yaml`. It has one profile, `default`, listing everything. Fill in `install:` for git packages that need a post-clone step, and make it a git repo:
+
+```
+cd ~/lshed && git init && git remote add origin git@github.com:me/harness.git
+lshed sync
+```
+
+### Every day: edit, save, sync
+
+You edit skills where the agent reads them, in `~/.claude`. The shed does not change by itself.
+
+```
+lshed status          # what profile is applied, what drifted, what is new
+lshed diff            # file-level differences between ~/.claude and the shed
+lshed save            # copy local edits into the shed (or: lshed save skills/add-drivers)
+lshed sync            # commit the shed, pull, push
+```
+
+`save` is the only path from `~/.claude` to the shed, and it only works for parts the shed owns (`file:` sources). `sync` warns if you have unsaved edits so you do not push a shed that is behind your machine.
+
+### A new machine
+
+```
+git clone git@github.com:me/harness.git ~/lshed
+lshed restore default --shed ~/lshed
+```
+
+```
+  + package gstack  (clone https://github.com/garrytan/gstack.git @main → 253d1df)
+  + package claude-plugins-official  (claude plugin marketplace add anthropics/claude-plugins-official)
+  + package exa  (claude plugin install exa@claude-plugins-official  (전에 3.4.1; 고정은 안 됨))
+  + skills/add-drivers
+  + skills/domain-modeling
+  + mcp:notion  (${NOTION_AUTHORIZATION})
+  + lshed/instructions/main.md
+  + CLAUDE.md
+
+프로필 "default" 적용: 배치 5, 제거 0, 패키지 설치 3
+
+설치 명령 1개를 실행하지 않았습니다. 확인 후 '--yes' 로 다시 실행하거나 직접 돌리세요:
+  cd /home/me/.claude/skills/gstack && ./setup
+
+환경변수가 없는 항목이 있습니다. 시크릿 값은 창고에 담지 않으므로 이 기기의 셸 환경에 넣으세요 (예: ~/.zshrc 의 export):
+  mcp:notion: NOTION_AUTHORIZATION
+```
+
+Two things need you afterwards. Package `install:` commands are shell commands from a repository you cloned, so `restore` shows them and stops; run them yourself or rerun with `--yes`. MCP servers reference secrets as `${VAR}`; export the variables in your shell and Claude Code fills them in. From then on `lshed restore` with no arguments reapplies the last profile, and the shed location is remembered.
+
+### Profiles
+
+A profile is a list of ids per category. Add as many as you like to `lshed.yaml`:
+
+```yaml
+profiles:
+  default:
+    packages: [gstack, claude-plugins-official, exa]
+    skills: [add-drivers, domain-modeling, grilling]
+    instructions: [main]
+    mcp: [notion]
+  server:                       # headless box: no browser toolkit, no MCP
+    skills: [add-drivers]
+    instructions: [main, server-rules]
+```
+
+```
+lshed restore server
+  - skills/domain-modeling
+  - skills/grilling
+  - mcp:notion
+  = skills/add-drivers
+  ~ CLAUDE.md
+  + lshed/instructions/server-rules.md
+```
+
+Switching removes only what the previous profile placed (`-`), keeps what both use (`=`), and rewrites what changed (`~`). Everything removed or overwritten goes to `~/.claude/lshed/backups/<timestamp>/` first. Packages are additive: a profile that does not list `gstack` leaves the clone alone. `--dry-run` prints this plan without touching anything.
+
+Instructions fragments are ordered. `restore` writes a `CLAUDE.md` that `@`-imports each fragment, so editing a fragment in the shed shows up on the next `restore` and there is nothing to merge.
+
+### Adding things later
+
+Write a new skill, add an MCP server with `claude mcp add`, clone a toolkit into `~/.claude/skills/`. Then:
+
+```
+$ lshed add
+창고에 없는 항목 3개 (넣으려면 lshed add <key...> 또는 --all):
+    skills/paper-review
+    mcp/linear
+  ≡ packages/superpowers  github:obra/superpowers@main
+  · 패키지 gstack 가 생성한 것 53개는 담지 않습니다
+
+$ lshed add paper-review mcp/linear
+  + skills/paper-review
+  + mcp/linear  (시크릿 → ${LINEAR_API_KEY})
+
+2개를 창고에 넣고 프로필 "default" 에 추가했습니다. 창고를 커밋하세요: /home/me/lshed
+```
+
+`add` classifies exactly like `init`, appends to `lshed.yaml` without disturbing your comments, adds the parts to the current profile and to the managed set. Without keys it only lists. `status` shows the count as `창고 밖`. To put a part that is already in the shed into another profile, edit `profiles:` by hand; `add` tells you when that is the case.
+
+### Keeping packages current
+
+```
+lshed status                # shows "253d1df ≠ lock 0d1bd56 → lshed update" when a clone moved
+lshed update                # fast-forward every package in the profile, refresh lshed.lock
+lshed update gstack --yes   # one package, and run its install: afterwards
+```
+
+Git packages are pinned by commit in `lshed.lock`; a new machine gets exactly that commit. Plugins cannot be pinned, so the lock records what got installed and `status` says when it differs from the machine you came from.
+
+### Housekeeping
+
+```
+lshed list                  # everything in the shed and which profiles use it
+lshed list --unused         # parts no profile lists
+lshed remove skills/old     # delete from the shed (refused while a profile uses it)
+lshed prune --yes           # delete everything unused
+```
+
+`remove` and `prune` delete from the shed without a backup; the shed lives in git, so commit before you prune.
+
+### Reading the output
+
+| Mark | Meaning |
+|---|---|
+| `+` | placed / added |
+| `=` | already identical, nothing done |
+| `~` | existed with different content, replaced (backed up) |
+| `-` | removed (backed up) or excluded |
+| `≡` | package: recorded by source, not copied |
+| `·` | generated by an installer, skipped |
+| `!` | needs your attention |
+| `↑` `↓` | pushed / pulled (sync), updated (update) |
+
+Errors go to stderr with exit code 1. Everything else is on stdout.
+
 ## The manifest
 
-`lshed.yaml` lives at the root of the shed. `init` generates it; edit it by hand from then on.
+`lshed.yaml` lives at the root of the shed. `init` generates it; edit it by hand from then on. `add` and `remove` edit it for you and keep your comments.
 
 ```yaml
 version: 1
 agent: claude-code
+exclude: [skills/_gstack-command]   # things init/add must not pick up
+ignore: [dist]                      # extra names never copied (adds to the built-in list)
 
 components:
   skills:
@@ -64,22 +225,32 @@ components:
   instructions:
     - id: base                    # file:./instructions/base.md
     - id: research-style
+  mcp:
+    - id: exa                     # file:./mcp/exa.json — secrets replaced by ${VAR}
+
+packages:
+  - id: gstack
+    source: github:garrytan/gstack@main
+    into: skills/gstack
+    install: ./setup
 
 profiles:
   research:
+    packages: [gstack]
     skills: [paper-review]
     agents: [reviewer]
     instructions: [base, research-style]    # order matters
+    mcp: [exa]
   teaching:
     skills: [grading-helper]
     commands: [summarize]
     instructions: [base]
 ```
 
-- Component `source` accepts `file:<path relative to the shed>`. Package `source` accepts `github:owner/repo@ref` or `git:<url>#ref`.
-- Category names come from the adapter. For Claude Code: `skills`, `agents`, `commands`, `instructions`.
-- `ignore:` at the top level adds to the built-in list of things never copied: `node_modules`, `.git`, `__pycache__`, `.venv`, cache directories, `*.log`. Build output like `dist/` is not ignored by default, since some skills ship it. Add it yourself if your parts rebuild from source.
-- Instructions are not merged. `restore` writes a `CLAUDE.md` that `@`-imports each fragment in order, so a fragment edit shows up without re-running anything. Your original `CLAUDE.md` is backed up the first time.
+- Component `source` accepts `file:<path relative to the shed>`. Package `source` accepts `github:owner/repo@ref`, `git:<url>#ref`, `claude-marketplace:<owner/repo>`, `claude-plugin:<name>@<marketplace>`.
+- Category names come from the adapter. For Claude Code: `skills`, `agents`, `commands`, `instructions`, `mcp`.
+- `ignore:` adds to the built-in list of things never copied: `node_modules`, `.git`, `__pycache__`, `.venv`, cache directories, `*.log`. Build output like `dist/` is not ignored by default, since some skills ship it.
+- `exclude:` lists parts that exist locally but must not enter the shed. `init --exclude` writes it.
 
 ## Three kinds of things
 
@@ -87,77 +258,71 @@ A real `~/.claude` mixes three kinds of content, and they need different handlin
 
 | Kind | Example | What lshed does |
 |---|---|---|
-| **Authored** | a skill you wrote, your `CLAUDE.md` | copies it into the shed |
-| **Installed** | a toolkit you `git clone`d, a plugin | records source + commit; `restore` clones it back |
+| **Authored** | a skill you wrote, your `CLAUDE.md`, an MCP server you added | copies it into the shed |
+| **Installed** | a toolkit you `git clone`d, a plugin | records source + commit; `restore` clones or installs it back |
 | **Generated** | stub skills an installer wrote for you | skips them; they return when the installer runs |
 
-`init` sorts this out for you. A directory with a `.git` and a remote becomes a **package**. A skill whose symlink points inside a package is treated as generated and skipped. Everything else is authored and copied.
+A directory with a `.git` and a remote becomes a **package**. A skill whose symlink points inside a package is treated as generated and skipped. Everything else is authored and copied. The rules that keep this safe:
 
-```yaml
-packages:
-  - id: gstack
-    source: github:garrytan/gstack@main   # git:<url>#ref for other hosts
-    into: skills/gstack                   # where it lives under ~/.claude
-    install: ./setup                      # optional; run after clone, only with --yes
-
-profiles:
-  default:
-    packages: [gstack]
-    skills: [add-drivers, domain-modeling]
-```
-
-`lshed.lock` pins each package to a commit, so a fresh machine gets the same version you had. `lshed update` moves it forward.
+- A package that is already present is never touched by `restore`. Your local checkout is yours.
+- `install:` is a shell command. `restore` and `update` **print it and stop** unless you pass `--yes`. Plugin installs go through Claude Code's own package manager and run without it; `--yes` is forwarded as `-y` for plugins that declare an install command.
+- Packages are not part of the managed set. Switching profiles never deletes a clone.
 
-Claude Code plugins are packages too, with their own scheme. `init` finds them in `~/.claude/plugins`:
+Claude Code plugins are packages with their own scheme. `init` finds user-scope ones in `~/.claude/plugins`; `restore` adds the marketplace first, then runs `claude plugin install`. Project-scope plugins belong to their project and are not recorded.
 
-```yaml
-packages:
-  - id: claude-plugins-official
-    source: claude-marketplace:anthropics/claude-plugins-official
-  - id: exa
-    source: claude-plugin:exa@claude-plugins-official
-```
+## MCP servers and secrets
 
-`restore` adds the marketplace, then runs `claude plugin install exa@claude-plugins-official`. Plugins cannot be pinned to a version, so the lock records whatever got installed and `status` tells you when it differs from the machine you came from. Plugins that bundle MCP servers bring them along.
+User-scope MCP servers live in `~/.claude.json`, next to machine IDs and session state. lshed treats each server as a component of category `mcp`: the shed holds `mcp/<name>.json`, and `restore` edits only the `mcpServers.<name>` key of `~/.claude.json`, leaving everything else in that file alone.
 
-Rules that keep this safe:
+**No secret value enters the shed.** `init` and `add` replace values under `env` and `headers` whose key looks like a secret (`key`, `token`, `secret`, `pass`, `auth`, `credential`, `cookie`, `session`) with a `${VAR}` placeholder:
 
-- A package that is already present is never touched by `restore`. Your local checkout is yours.
-- `install:` is a shell command. `restore` and `update` **print it and stop** unless you pass `--yes`. Plugin installs go through Claude Code's own package manager and run without it; `--yes` is forwarded as `-y` for plugins that declare an install command.
-- Packages are not part of the managed set. Switching profiles never deletes a clone.
-- Installers sometimes create aliases without symlinks, which `init` cannot tell from authored skills. Leave those out with `--exclude`:
-
-```bash
-lshed init --shed ~/harness --exclude _gstack-command connect-chrome
+```json
+{ "type": "stdio", "command": "npx", "args": ["-y", "exa-mcp-server"],
+  "env": { "EXA_API_KEY": "${EXA_API_KEY}" } }
+{ "type": "http", "url": "https://mcp.notion.com/mcp",
+  "headers": { "Authorization": "Bearer ${NOTION_AUTHORIZATION}" } }
 ```
 
+`restore` writes the placeholder as is. Claude Code expands `${VAR}` from the environment when it starts the server, so the value only ever lives in your shell (`export EXA_API_KEY=...` in `~/.zshrc`, or however you manage secrets). `restore` and `status` list the variables the profile needs that are not set. The heuristic is a suggestion: edit the JSON in the shed to add or remove placeholders, and `init` warns when something in `args` or `url` looks like a token. `save` keeps existing placeholders and masks new secret-looking keys, so a rotated key never leaks into the shed by accident. `diff` compares with placeholders as wildcards, so a machine holding real values is not drift.
+
 ## Commands
 
 ```
 lshed init [--shed <dir>] [--profile <name>] [--exclude <id...>]
+lshed add [keys...] [--all]                     put things that appeared since init into the shed
 lshed restore [profile] [--dry-run] [--no-backup] [--yes]
-lshed update [ids...] [--dry-run] [--yes]       pull packages forward, refresh lshed.lock
-lshed status                                    applied profile, managed paths, drift, packages
-lshed diff                                      files that differ between local and shed
+lshed status                                    applied profile, drift, packages, missing env, new things
+lshed diff                                      files (or JSON keys) that differ between local and shed
 lshed save [ids...]                             copy local edits back into the shed
+lshed sync [-m <msg>] [--no-push] [--dry-run]   commit the shed, pull --rebase, push
+lshed update [ids...] [--dry-run] [--yes]       pull packages forward, refresh lshed.lock
 lshed list [--unused]                           what is in the shed, and which profiles use it
 lshed remove <key>                              drop a component or package from the shed
 lshed prune [--yes]                             drop everything no profile uses
 ```
 
-`remove` and `prune` delete from the shed without a backup. The shed is meant to live in git; commit before you prune. Both refuse to touch anything a profile still lists, so the way to retire a part is to take it out of the profiles first.
+Keys are `category/id`, or just `id` when unambiguous: `skills/paper-review`, `mcp/exa`, `packages/gstack`.
 
-Global options: `--shed <dir>` (or `LSHED_HOME`; after the first restore lshed remembers it), `--root <dir>` (agent config root, default `~/.claude`).
+Global options: `--shed <dir>` (or `LSHED_HOME`; after the first restore lshed remembers it), `--root <dir>` (agent config root, default `~/.claude` or `CLAUDE_CONFIG_DIR`).
 
 ### What `restore` does
 
-0. Clones any package in the profile that is missing, at the commit in `lshed.lock`.
+0. Installs any package in the profile that is missing, at the version in `lshed.lock`.
 1. Removes paths that the **previous** profile placed and the new one doesn't need.
-2. Copies every part of the new profile into place.
+2. Copies every part of the new profile into place; writes every MCP entry into `~/.claude.json`.
 3. Regenerates the instructions file.
 
 Anything it overwrites or removes is backed up first under `~/.claude/lshed/backups/<timestamp>/`, unless you pass `--no-backup`. Files lshed never placed are left alone. `--dry-run` prints the plan and writes nothing.
 
+### What `sync` does
+
+1. Warns if `diff` shows local edits you have not saved.
+2. Commits everything in the shed (message names the changed parts, or `-m`).
+3. If `origin` exists: `git pull --rebase`, then `git push` (sets the upstream the first time).
+4. If commits came in, tells you to run `lshed restore`.
+
+On a conflict it aborts the rebase, leaves the shed clean with your commit intact, and tells you to resolve with git. Without a remote it only commits. It never runs `save` for you.
+
 ### Ownership
 
 The shed is the source of truth for authored parts: `save` copies local edits back for `file:` components. Packages are owned by their upstream: `update` pulls them, `save` ignores them.
@@ -166,31 +331,37 @@ The shed is the source of truth for authored parts: `save` copies local edits ba
 
 ```
 <shed>/
-  lshed.yaml
-  skills/<id>/            agents/<id>.md        commands/<id>.md        instructions/<id>.md
+  lshed.yaml                                    manifest
+  lshed.lock                                    package versions (generated)
+  skills/<id>/    agents/<id>.md    commands/<id>.md    instructions/<id>.md
+  mcp/<id>.json                                 secrets as ${VAR}
 
 ~/.claude/
   skills/ agents/ commands/ CLAUDE.md           ← placed by restore
   lshed/state.json                              ← which profile, which paths are managed
   lshed/instructions/<id>.md                    ← fragments imported by CLAUDE.md
   lshed/backups/<timestamp>/                    ← whatever restore replaced
+~/.claude.json  mcpServers.<id>                 ← one key per mcp component; the rest of the file is untouched
 ```
 
-`state.json` is per machine and is not part of the shed.
+`state.json` is per machine and is not part of the shed. If `CLAUDE_CONFIG_DIR` is set, lshed uses it as the root and expects `.claude.json` inside it, as Claude Code does.
 
 ## Not in scope (yet)
 
-- MCP servers and secrets. Planned: the manifest names the keys, values are injected locally, nothing secret enters the shed.
+- Secrets beyond "name the variable". Encrypted values, `op://` references and OS keychains are possible later; today lshed is deliberately no better than dotfiles here.
+- Project-scope MCP servers (`.mcp.json`, `~/.claude.json` `projects.*`) and project-scope plugins. They belong to the project.
 - `settings.json` merging (hooks, permissions).
-- `sync` (a git pull/push wrapper). Use git in the shed directly for now.
-- MCP servers configured by hand in `~/.claude.json`. Plugin-bundled ones are covered.
-- Windows and macOS have not been tested. The code avoids platform-specific paths, but treat 0.1 as Linux/WSL.
+- Windows and macOS have not been tested. The code avoids platform-specific paths, but treat this as Linux/WSL for now.
 
 ## Troubleshooting
 
 - **"창고 위치를 모릅니다"** — pass `--shed <dir>` or set `LSHED_HOME`. After one successful `restore`, lshed remembers it.
 - **restore replaced my `CLAUDE.md`** — it is in `~/.claude/lshed/backups/<timestamp>/CLAUDE.md`. Move its content into a fragment in the shed and add that fragment to your profile.
-- **I edited a skill locally and want to keep it** — `lshed diff` to see, `lshed save <id>` to push it into the shed, then commit the shed.
+- **I edited a skill locally and want to keep it** — `lshed diff` to see, `lshed save <id>` to push it into the shed, then `lshed sync`.
+- **`status` says a package differs from the lock** — something updated the clone or plugin behind lshed's back (Claude Code auto-updates plugins). `lshed update` records the new version.
+- **`status` keeps listing the same new things** — they are installer aliases or scratch. Add them to `exclude:` in `lshed.yaml`.
+- **restore says an MCP variable is missing** — export it in your shell profile and restart Claude Code. The placeholder in `~/.claude.json` is correct; Claude Code fills it at startup.
+- **sync stopped on a conflict** — `cd <shed> && git pull --rebase`, resolve, `git rebase --continue`, then `lshed sync` again.
 
 ## License