lshed 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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.

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:
@@ -67,8 +228,15 @@ components:
   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
@@ -79,25 +247,10 @@ profiles:
     instructions: [base]
 ```
 
-- Component `source` accepts `file:<path relative to the shed>`. Package `source` accepts `github:owner/repo@ref` or `git:<url>#ref`.
+- 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:` 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.
-
-## MCP servers and secrets
-
-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.
-
-**No secret value enters the shed.** `init` replaces values under `env` and `headers` whose key looks like a secret (`key`, `token`, `secret`, `pass`, `auth`, `credential`, `cookie`, `session`) with a `${VAR}` placeholder:
-
-```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.
+- `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
 
@@ -105,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.
-
-```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 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:
 
-Claude Code plugins are packages too, with their own scheme. `init` finds them in `~/.claude/plugins`:
+- 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.
 
-```yaml
-packages:
-  - id: claude-plugins-official
-    source: claude-marketplace:anthropics/claude-plugins-official
-  - id: exa
-    source: claude-plugin:exa@claude-plugins-official
-```
+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.
 
-`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.
+## MCP servers and secrets
 
-Rules that keep this safe:
+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.
 
-- 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`:
+**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:
 
-```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.
@@ -184,16 +331,17 @@ 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
-  mcp/<id>.json                                 ← secrets as ${VAR}
+  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
-~/.claude.json  mcpServers.<id>                 ← one key per mcp component; the rest of the file is untouched
   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. If `CLAUDE_CONFIG_DIR` is set, lshed uses it as the root and expects `.claude.json` inside it, as Claude Code does.
@@ -201,16 +349,19 @@ The shed is the source of truth for authored parts: `save` copies local edits ba
 ## Not in scope (yet)
 
 - 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.*`). They belong to the project.
+- 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.
-- 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
 

package/dist/cli.js

@@ -3,8 +3,8 @@
 // src/cli.ts
 import { Command } from "commander";
 import { createRequire } from "module";
-import os2 from "os";
-import path17 from "path";
+import os3 from "os";
+import path19 from "path";
 
 // src/adapters/claude-code.ts
 import { promises as fs4 } from "fs";
@@ -493,6 +493,8 @@ var ManifestSchema = z.object({
   agent: z.string().default("claude-code"),
   /** 창고에 담지 않을 이름들. 기본값(DEFAULT_IGNORE)에 더해진다. */
   ignore: z.array(z.string()).optional(),
+  /** 로컬에 있어도 창고에 넣지 않을 부품 ("id" 또는 "category/id"). init --exclude 가 적고 add/status 가 따른다. */
+  exclude: z.array(z.string()).optional(),
   components: ComponentsSchema.default({}),
   packages: z.array(PackageSchema).default([]),
   profiles: z.record(z.string(), ProfileSchema).default({})
@@ -558,12 +560,6 @@ function effectiveSource(category, c, kind = "dir") {
   const ext = kind === "file" ? ".md" : kind === "entry" ? ".json" : "";
   return c.source ?? `file:./${category}/${c.id}${ext}`;
 }
-function stringifyManifest(m) {
-  const out = { ...m };
-  if (!m.packages.length) delete out.packages;
-  if (!m.ignore?.length) delete out.ignore;
-  return YAML.stringify(out, { lineWidth: 0 });
-}
 function packagesOf(m, profile) {
   const ids = m.profiles[profile]?.[PACKAGES] ?? [];
   return ids.map((id) => m.packages.find((p) => p.id === id));
@@ -701,7 +697,8 @@ function abs(ctx, rel) {
 
 // src/core/init.ts
 import { promises as fs11 } from "fs";
-import path14 from "path";
+import path16 from "path";
+import YAML4 from "yaml";
 
 // src/core/instructions.ts
 import path10 from "path";
@@ -725,10 +722,6 @@ ${f.content.trimEnd()}
 `).join("\n");
 }
 
-// src/core/packages.ts
-import { promises as fs9 } from "fs";
-import path12 from "path";
-
 // src/lock.ts
 import { promises as fs8 } from "fs";
 import path11 from "path";
@@ -753,7 +746,12 @@ async function writeLock(shed, lock) {
   await fs8.writeFile(path11.join(shed, LOCK_FILE), "# generated by lshed \u2014 do not edit; 'lshed update' refreshes it\n" + YAML2.stringify(sorted));
 }
 
+// src/core/discover.ts
+import path13 from "path";
+
 // src/core/packages.ts
+import { promises as fs9 } from "fs";
+import path12 from "path";
 async function detectPackages(ctx, found) {
   const out = [];
   for (const inst of installersFor(ctx)) out.push(...await inst.detect(ctx, found));
@@ -868,9 +866,69 @@ async function updatePackages(ctx, pkgs, opts = {}) {
   return res;
 }
 
+// src/core/discover.ts
+var keyOf = (f) => `${f.category}/${f.id}`;
+async function discover(ctx, exclude = []) {
+  const isExcluded = (cat, id) => exclude.some((e) => e === id || e === `${cat}/${id}`);
+  const excluded = [];
+  const items = [];
+  const all = await ctx.adapter.scan();
+  const pkgs = await detectPackages(ctx, all);
+  const kept = pkgs.filter((p) => {
+    if (isExcluded("packages", p.id)) {
+      excluded.push(`packages/${p.id}`);
+      return false;
+    }
+    return true;
+  });
+  const generated = await detectGenerated(all, kept);
+  for (const p of kept) items.push({ kind: "package", category: "packages", id: p.id, pkg: p });
+  for (const cat of ctx.adapter.categories()) {
+    for (const f of all.filter((f2) => f2.category === cat.name)) {
+      if (pkgs.some((p) => p.path === f.path) || generated.has(keyOf(f))) continue;
+      if (isExcluded(f.category, f.id)) {
+        excluded.push(keyOf(f));
+        continue;
+      }
+      items.push({ kind: "component", category: cat.name, id: f.id, path: f.path, cat });
+    }
+  }
+  for (const cat of ctx.adapter.entries()) {
+    const all2 = await cat.read();
+    for (const id of Object.keys(all2).sort()) {
+      if (isExcluded(cat.name, id)) {
+        excluded.push(`${cat.name}/${id}`);
+        continue;
+      }
+      if (!/^[\w.-]+$/.test(id)) {
+        ctx.log(`  ! ${cat.name}/${id}: \uC774\uB984\uC5D0 \uC4F8 \uC218 \uC5C6\uB294 \uBB38\uC790\uAC00 \uC788\uC5B4 \uAC74\uB108\uB700`);
+        continue;
+      }
+      items.push({ kind: "entry", category: cat.name, id, value: all2[id], cat });
+    }
+  }
+  return { items, generated, excluded };
+}
+function notInManifest(m, d) {
+  return d.items.filter(
+    (f) => f.kind === "package" ? !m.packages.some((p) => p.id === f.id) : !(m.components[f.category] ?? []).some((c) => c.id === f.id)
+  );
+}
+function inManifestNotInProfile(m, profile, d) {
+  const p = m.profiles[profile] ?? {};
+  return d.items.filter((f) => !notInManifest(m, d).includes(f)).filter((f) => !(p[f.category] ?? []).includes(f.id)).map(keyOf);
+}
+function shortRev(rev) {
+  return /^[0-9a-f]{40}$/.test(rev) ? rev.slice(0, 7) : rev;
+}
+
+// src/core/ingest.ts
+import path15 from "path";
+import { isSeq, isMap } from "yaml";
+
 // src/core/entries.ts
 import { promises as fs10 } from "fs";
-import path13 from "path";
+import path14 from "path";
 var SECRET_KEY_RE = /key|token|secret|pass|auth|credential|cookie|session/i;
 var PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
 function placeholdersIn(v) {
@@ -990,124 +1048,114 @@ async function readEntryFile(p) {
   }
 }
 async function writeEntryFile(p, v) {
-  await fs10.mkdir(path13.dirname(p), { recursive: true });
+  await fs10.mkdir(path14.dirname(p), { recursive: true });
   await fs10.writeFile(p, JSON.stringify(v, null, 2) + "\n");
 }
 
-// src/core/init.ts
-async function init(ctx, opts = {}) {
-  const profileName = opts.profile ?? "default";
-  const exclude = opts.exclude ?? [];
-  const skipped = [];
-  if (await exists(manifestPath(ctx))) {
-    throw new Error(`\uC774\uBBF8 \uCD08\uAE30\uD654\uB41C \uCC3D\uACE0\uC785\uB2C8\uB2E4: ${manifestPath(ctx)}
-  \uB2E4\uB978 \uD658\uACBD\uC758 \uC124\uC815\uC744 \uC774 \uCC3D\uACE0\uB85C \uAC00\uC838\uC624\uB824\uBA74 'lshed restore' \uD6C4 'lshed save' \uB97C \uC4F0\uC138\uC694.`);
-  }
-  const all = await ctx.adapter.scan();
-  const m = { version: 1, agent: ctx.adapter.name, components: {}, packages: [], profiles: { [profileName]: {} } };
-  const isExcluded = (cat, id) => exclude.some((e) => e === id || e === `${cat}/${id}`);
-  const pkgs = (await detectPackages(ctx, all)).filter((p) => !isExcluded("", p.id));
-  const generated = await detectGenerated(all, pkgs);
-  const found = all.filter((f) => !pkgs.some((p) => p.path === f.path) && !generated.has(`${f.category}/${f.id}`));
-  for (const p of pkgs) {
-    m.packages.push(p.into ? { id: p.id, source: p.source, into: p.into } : { id: p.id, source: p.source });
-    const rev = /^[0-9a-f]{40}$/.test(p.rev) ? p.rev.slice(0, 7) : p.rev;
-    ctx.log(`  \u2261 package ${p.id}  ${p.source} @${rev}  (\uCC38\uC870\uB9CC \uAE30\uB85D)`);
-  }
-  if (pkgs.length) m.profiles[profileName][PACKAGES] = pkgs.map((p) => p.id);
-  for (const [key, by] of generated) ctx.log(`  \xB7 ${key}  (${by} \uAC00 \uC0DD\uC131\uD55C \uAC83 \u2192 \uAC74\uB108\uB700)`);
-  const managed = [];
-  let copied = 0;
-  for (const cat of ctx.adapter.categories()) {
-    const mine = found.filter((f) => f.category === cat.name && !isExcluded(f.category, f.id));
-    for (const f of found.filter((f2) => f2.category === cat.name && isExcluded(f2.category, f2.id))) {
-      skipped.push(`${f.category}/${f.id}`);
-      ctx.log(`  - ${f.category}/${f.id}  (--exclude)`);
+// src/core/ingest.ts
+function seqAt(doc, p) {
+  let node = doc.getIn(p);
+  if (!isSeq(node)) {
+    node = doc.createNode([]);
+    doc.setIn(p, node);
+  }
+  return node;
+}
+function pushUnique(seq, value) {
+  if (!seq.items.some((it) => (isMap(it) ? it.get("id") : String(it)) === value)) seq.add(value);
+}
+async function ingest(ctx, doc, profile, items, lock) {
+  const out = { managed: [], copied: 0, packages: [] };
+  for (const f of items) {
+    if (f.kind === "package") {
+      const p = f.pkg;
+      const node = doc.createNode(p.into ? { id: p.id, source: p.source, into: p.into } : { id: p.id, source: p.source });
+      if (p.into) node.comment = " install: ./setup    # \u2190 \uBCF5\uC6D0 \uD6C4 \uC2E4\uD589\uD560 \uBA85\uB839\uC774 \uC788\uC73C\uBA74 \uCC44\uC6B0\uC138\uC694 (--yes \uB85C \uC2E4\uD589)";
+      const seq = seqAt(doc, [PACKAGES]);
+      if (!seq.items.some((it) => isMap(it) && it.get("id") === p.id)) seq.add(node);
+      pushUnique(seqAt(doc, ["profiles", profile, PACKAGES]), p.id);
+      lock.packages[p.id] = { source: p.source, rev: p.rev };
+      out.packages.push(p.id);
+      ctx.log(`  \u2261 package ${p.id}  ${p.source} @${shortRev(p.rev)}  (\uCC38\uC870\uB9CC \uAE30\uB85D)`);
+      continue;
     }
-    if (!mine.length) continue;
-    m.components[cat.name] = [];
-    m.profiles[profileName][cat.name] = [];
-    for (const f of mine) {
-      const dst = path14.join(ctx.shed, cat.root, cat.kind === "dir" ? f.id : `${f.id}.md`);
+    if (f.kind === "component") {
+      const dst = path15.join(ctx.shed, f.cat.root, f.cat.kind === "dir" ? f.id : `${f.id}.md`);
       await copyTree(f.path, dst, ignoreOf(ctx));
-      m.components[cat.name].push({ id: f.id });
-      m.profiles[profileName][cat.name].push(f.id);
-      managed.push(targetRel(cat, f.id));
-      copied++;
-      ctx.log(`  + ${cat.name}/${f.id}`);
-    }
-  }
-  for (const cat of ctx.adapter.entries()) {
-    const all2 = await cat.read();
-    const ids = Object.keys(all2).sort();
-    for (const id of ids.filter((id2) => isExcluded(cat.name, id2))) {
-      skipped.push(`${cat.name}/${id}`);
-      ctx.log(`  - ${cat.name}/${id}  (--exclude)`);
-    }
-    const mine = ids.filter((id) => !isExcluded(cat.name, id));
-    if (!mine.length) continue;
-    m.components[cat.name] = [];
-    m.profiles[profileName][cat.name] = [];
-    for (const id of mine) {
-      if (!/^[\w.-]+$/.test(id)) {
-        ctx.log(`  ! ${cat.name}/${id}: \uC774\uB984\uC5D0 \uC4F8 \uC218 \uC5C6\uB294 \uBB38\uC790\uAC00 \uC788\uC5B4 \uAC74\uB108\uB700`);
-        continue;
-      }
-      const masked = mask(id, all2[id], cat);
-      await writeEntryFile(path14.join(ctx.shed, cat.name, `${id}.json`), masked);
-      m.components[cat.name].push({ id });
-      m.profiles[profileName][cat.name].push(id);
-      managed.push(targetRel(cat, id));
-      copied++;
+      ctx.log(`  + ${f.category}/${f.id}`);
+    } else {
+      const masked = mask(f.id, f.value, f.cat);
+      await writeEntryFile(path15.join(ctx.shed, f.category, `${f.id}.json`), masked);
       const vars = placeholdersIn(masked);
-      ctx.log(`  + ${cat.name}/${id}${vars.length ? `  (\uC2DC\uD06C\uB9BF \u2192 ${vars.map((v) => "${" + v + "}").join(", ")})` : ""}`);
-      for (const where of suspiciousStrings(masked)) ctx.log(`    ! ${where} \uAC00 \uC2DC\uD06C\uB9BF\uCC98\uB7FC \uBCF4\uC785\uB2C8\uB2E4. \uCC3D\uACE0\uC758 ${cat.name}/${id}.json \uC5D0\uC11C \${VAR} \uB85C \uBC14\uAFB8\uC138\uC694`);
+      ctx.log(`  + ${f.category}/${f.id}${vars.length ? `  (\uC2DC\uD06C\uB9BF \u2192 ${vars.map((v) => "${" + v + "}").join(", ")})` : ""}`);
+      for (const where of suspiciousStrings(masked)) ctx.log(`    ! ${where} \uAC00 \uC2DC\uD06C\uB9BF\uCC98\uB7FC \uBCF4\uC785\uB2C8\uB2E4. \uCC3D\uACE0\uC758 ${f.category}/${f.id}.json \uC5D0\uC11C \${VAR} \uB85C \uBC14\uAFB8\uC138\uC694`);
     }
+    const comps = seqAt(doc, ["components", f.category]);
+    if (!comps.items.some((it) => isMap(it) && it.get("id") === f.id)) comps.add(doc.createNode({ id: f.id }));
+    pushUnique(seqAt(doc, ["profiles", profile, f.category]), f.id);
+    out.managed.push(targetRel(f.cat, f.id));
+    out.copied++;
   }
+  return out;
+}
+function tidy(doc) {
+  const pk = doc.get(PACKAGES);
+  if (isSeq(pk) && !pk.items.length) doc.delete(PACKAGES);
+}
+
+// src/core/init.ts
+var MANIFEST_HEADER = "# lshed manifest \u2014 edit freely. Reference: https://github.com/LeeSongHeon-LSH/lshed\n";
+async function init(ctx, opts = {}) {
+  const profileName = opts.profile ?? "default";
+  if (await exists(manifestPath(ctx))) {
+    throw new Error(`\uC774\uBBF8 \uCD08\uAE30\uD654\uB41C \uCC3D\uACE0\uC785\uB2C8\uB2E4: ${manifestPath(ctx)}
+  \uC774 \uD658\uACBD\uC5D0 \uC0C8\uB85C \uC0DD\uAE34 \uAC83\uC744 \uAE30\uC874 \uCC3D\uACE0\uC5D0 \uB123\uC73C\uB824\uBA74 'lshed add' \uB97C, \uB2E4\uB978 \uD658\uACBD\uC758 \uC124\uC815\uC744 \uAC00\uC838\uC624\uB824\uBA74 'lshed restore' \uD6C4 'lshed save' \uB97C \uC4F0\uC138\uC694.`);
+  }
+  const d = await discover(ctx, opts.exclude);
+  for (const [key, by] of d.generated) ctx.log(`  \xB7 ${key}  (${by} \uAC00 \uC0DD\uC131\uD55C \uAC83 \u2192 \uAC74\uB108\uB700)`);
+  for (const key of d.excluded) ctx.log(`  - ${key}  (--exclude)`);
+  const exclude = opts.exclude?.length ? { exclude: [...opts.exclude] } : {};
+  const doc = new YAML4.Document({ version: 1, agent: ctx.adapter.name, ...exclude, components: {}, packages: [], profiles: { [profileName]: {} } });
+  const lock = { version: 1, packages: {} };
+  await fs11.mkdir(ctx.shed, { recursive: true });
+  const res = await ingest(ctx, doc, profileName, d.items, lock);
+  const managed = [...res.managed];
+  let copied = res.copied;
   const instr = instructionsFile(ctx);
   if (await exists(instr)) {
     const text = await fs11.readFile(instr, "utf8");
     if (!isGenerated(text)) {
-      const dst = path14.join(ctx.shed, INSTRUCTIONS, "main.md");
-      await fs11.mkdir(path14.dirname(dst), { recursive: true });
+      const dst = path16.join(ctx.shed, INSTRUCTIONS, "main.md");
+      await fs11.mkdir(path16.dirname(dst), { recursive: true });
       await fs11.writeFile(dst, text);
       const fragRel = targetRel(INSTRUCTIONS, "main");
       await copyTree(dst, abs(ctx, fragRel), ignoreOf(ctx));
       managed.push(fragRel);
-      m.components[INSTRUCTIONS] = [{ id: "main" }];
-      m.profiles[profileName][INSTRUCTIONS] = ["main"];
+      doc.setIn(["components", INSTRUCTIONS], [{ id: "main" }]);
+      doc.setIn(["profiles", profileName, INSTRUCTIONS], ["main"]);
       copied++;
-      ctx.log(`  + ${INSTRUCTIONS}/main  (${path14.basename(instr)})`);
+      ctx.log(`  + ${INSTRUCTIONS}/main  (${path16.basename(instr)})`);
     }
   }
-  await fs11.mkdir(ctx.shed, { recursive: true });
-  let yamlText = stringifyManifest(m);
-  for (const p of pkgs) {
-    if (!p.into) continue;
-    yamlText = yamlText.replace(`    into: ${p.into}
-`, `    into: ${p.into}
-    # install: ./setup    # \u2190 \uBCF5\uC6D0 \uD6C4 \uC2E4\uD589\uD560 \uBA85\uB839\uC774 \uC788\uC73C\uBA74 \uCC44\uC6B0\uC138\uC694 (--yes \uB85C \uC2E4\uD589)
-`);
-  }
-  await fs11.writeFile(manifestPath(ctx), `# lshed manifest \u2014 edit freely. Reference: https://github.com/LeeSongHeon-LSH/lshed
-` + yamlText);
-  if (pkgs.length) {
-    await writeLock(ctx.shed, { version: 1, packages: Object.fromEntries(pkgs.map((p) => [p.id, { source: p.source, rev: p.rev }])) });
-  }
+  tidy(doc);
+  const yamlText = MANIFEST_HEADER + doc.toString({ lineWidth: 0 });
+  await fs11.writeFile(manifestPath(ctx), yamlText);
+  if (res.packages.length) await writeLock(ctx.shed, lock);
   await writeState(ctx.adapter, { profile: profileName, shed: ctx.shed, managed, appliedAt: (/* @__PURE__ */ new Date()).toISOString() });
   const parts = [`\uBD80\uD488 ${copied}\uAC1C`];
-  if (pkgs.length) parts.push(`\uD328\uD0A4\uC9C0 ${pkgs.length}\uAC1C`);
-  if (generated.size) parts.push(`\uC0DD\uC131\uBB3C ${generated.size}\uAC1C \uAC74\uB108\uB700`);
-  if (skipped.length) parts.push(`\uC81C\uC678 ${skipped.length}\uAC1C`);
+  if (res.packages.length) parts.push(`\uD328\uD0A4\uC9C0 ${res.packages.length}\uAC1C`);
+  if (d.generated.size) parts.push(`\uC0DD\uC131\uBB3C ${d.generated.size}\uAC1C \uAC74\uB108\uB700`);
+  if (d.excluded.length) parts.push(`\uC81C\uC678 ${d.excluded.length}\uAC1C`);
   ctx.log(`
 ${MANIFEST_FILE} \uC0DD\uC131: ${manifestPath(ctx)}  (${parts.join(", ")}, \uD504\uB85C\uD544 "${profileName}")`);
-  if (pkgs.some((p) => p.into)) ctx.log(`git \uD328\uD0A4\uC9C0\uC758 \uC124\uCE58 \uBA85\uB839(install:)\uC740 lshed.yaml \uC5D0\uC11C \uC9C1\uC811 \uCC44\uC6B0\uC138\uC694.`);
-  return { manifest: m, copied, skipped, packages: pkgs.map((p) => p.id), generated: [...generated.keys()] };
+  if (d.items.some((f) => f.kind === "package" && f.pkg.into)) ctx.log(`git \uD328\uD0A4\uC9C0\uC758 \uC124\uCE58 \uBA85\uB839(install:)\uC740 lshed.yaml \uC5D0\uC11C \uC9C1\uC811 \uCC44\uC6B0\uC138\uC694.`);
+  const manifest = parseManifest(yamlText);
+  return { manifest, copied, skipped: d.excluded, packages: res.packages, generated: [...d.generated.keys()] };
 }
 
 // src/core/restore.ts
 import { promises as fs12 } from "fs";
-import path15 from "path";
+import path17 from "path";
 async function restore(ctx, profileArg, opts = {}) {
   const backup = opts.backup ?? true;
   const state = await readState(ctx.adapter);
@@ -1126,7 +1174,7 @@ async function restore(ctx, profileArg, opts = {}) {
   const oldManaged = new Set(state?.managed ?? []);
   const toRemove = [...oldManaged].filter((r) => !newManaged.has(r)).sort();
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const backupDir = path15.join(ctx.adapter.root, LSHED_DIR, "backups", stamp);
+  const backupDir = path17.join(ctx.adapter.root, LSHED_DIR, "backups", stamp);
   const backedUp = [];
   const placed = [];
   const missingEnv = [];
@@ -1142,14 +1190,14 @@ async function restore(ctx, profileArg, opts = {}) {
       if (cur === void 0) return;
       backedUp.push(rel);
       if (opts.dryRun || !backup) return;
-      await writeEntryFile(path15.join(backupDir, en.cat.name, `${en.id}.json`), cur);
+      await writeEntryFile(path17.join(backupDir, en.cat.name, `${en.id}.json`), cur);
       return;
     }
     const from = abs(ctx, rel);
     if (!await exists(from)) return;
     backedUp.push(rel);
     if (opts.dryRun || !backup) return;
-    await copyTree(from, path15.join(backupDir, ...rel.split("/")), ignoreOf(ctx));
+    await copyTree(from, path17.join(backupDir, ...rel.split("/")), ignoreOf(ctx));
   }
   for (const rel of toRemove) {
     ctx.log(`  - ${rel}`);
@@ -1260,10 +1308,71 @@ function formatDiff(diffs) {
   return lines.join("\n");
 }
 
+// src/core/add.ts
+import { promises as fs13 } from "fs";
+import YAML5 from "yaml";
+async function candidates(ctx, m, profile, d) {
+  d ??= await discover(ctx, m.exclude);
+  return { fresh: notInManifest(m, d), notInProfile: inManifestNotInProfile(m, profile, d), generated: d.generated };
+}
+async function add(ctx, keys = [], opts = {}) {
+  const state = await readState(ctx.adapter);
+  if (!state) throw new Error("\uC801\uC6A9\uB41C \uD504\uB85C\uD544\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. \uBA3C\uC800 'lshed init' \uB610\uB294 'lshed restore <profile>' \uC744 \uC2E4\uD589\uD558\uC138\uC694.");
+  const m = await loadManifest(ctx);
+  const c = await candidates(ctx, m, state.profile);
+  if (!keys.length && !opts.all) {
+    if (!c.fresh.length) ctx.log("\uCC3D\uACE0\uC5D0 \uC5C6\uB294 \uC0C8 \uD56D\uBAA9\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    else {
+      ctx.log(`\uCC3D\uACE0\uC5D0 \uC5C6\uB294 \uD56D\uBAA9 ${c.fresh.length}\uAC1C (\uB123\uC73C\uB824\uBA74 lshed add <key...> \uB610\uB294 --all):`);
+      for (const f of c.fresh) ctx.log(`  ${f.kind === "package" ? "\u2261" : " "} ${keyOf(f)}${f.kind === "package" ? `  ${f.pkg.source}` : ""}`);
+    }
+    hint(ctx, c, state.profile);
+    return [];
+  }
+  let chosen = c.fresh;
+  if (keys.length) {
+    chosen = keys.map((raw) => {
+      const [a, b] = raw.includes("/") ? raw.split("/", 2) : [void 0, raw];
+      const hits = c.fresh.filter((f) => f.id === b && (a === void 0 || f.category === a));
+      if (!hits.length) {
+        const known = (m.components[a ?? ""] ?? []).some((x2) => x2.id === b) || Object.values(m.components).some((cs) => cs.some((x2) => x2.id === b)) || m.packages.some((p) => p.id === b);
+        throw new Error(known ? `"${raw}" \uB294 \uC774\uBBF8 \uCC3D\uACE0\uC5D0 \uC788\uC2B5\uB2C8\uB2E4. \uD504\uB85C\uD544\uC5D0 \uB123\uC73C\uB824\uBA74 lshed.yaml \uC758 profiles \uB97C \uACE0\uCE58\uC138\uC694.` : `"${raw}" \uB294 \uB85C\uCEEC\uC5D0\uC11C \uCC3E\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4. 'lshed add' \uB85C \uD6C4\uBCF4\uB97C \uBCF4\uC138\uC694.`);
+      }
+      if (hits.length > 1) throw new Error(`"${raw}" \uAC00 \uBAA8\uD638\uD569\uB2C8\uB2E4: ${hits.map(keyOf).join(", ")}`);
+      return hits[0];
+    });
+  }
+  if (!chosen.length) {
+    ctx.log("\uCC3D\uACE0\uC5D0 \uC5C6\uB294 \uC0C8 \uD56D\uBAA9\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    hint(ctx, c, state.profile);
+    return [];
+  }
+  const doc = YAML5.parseDocument(await fs13.readFile(manifestPath(ctx), "utf8"));
+  const lock = await readLock(ctx.shed);
+  const res = await ingest(ctx, doc, state.profile, chosen, lock);
+  tidy(doc);
+  await fs13.writeFile(manifestPath(ctx), doc.toString({ lineWidth: 0 }));
+  if (res.packages.length) await writeLock(ctx.shed, lock);
+  const managed = [.../* @__PURE__ */ new Set([...state.managed, ...res.managed])].sort();
+  await writeState(ctx.adapter, { ...state, managed, appliedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  const added = chosen.map(keyOf);
+  ctx.log(`
+${added.length}\uAC1C\uB97C \uCC3D\uACE0\uC5D0 \uB123\uACE0 \uD504\uB85C\uD544 "${state.profile}" \uC5D0 \uCD94\uAC00\uD588\uC2B5\uB2C8\uB2E4. \uCC3D\uACE0\uB97C \uCEE4\uBC0B\uD558\uC138\uC694: ${ctx.shed}`);
+  if (res.packages.some((id) => chosen.find((f) => f.id === id && f.kind === "package" && f.pkg.into))) ctx.log(`git \uD328\uD0A4\uC9C0\uC758 \uC124\uCE58 \uBA85\uB839(install:)\uC740 lshed.yaml \uC5D0\uC11C \uC9C1\uC811 \uCC44\uC6B0\uC138\uC694.`);
+  hint(ctx, { ...c, fresh: c.fresh.filter((f) => !chosen.includes(f)) }, state.profile);
+  return added;
+}
+function hint(ctx, c, profile) {
+  const byPkg = /* @__PURE__ */ new Map();
+  for (const by of c.generated.values()) byPkg.set(by, (byPkg.get(by) ?? 0) + 1);
+  for (const [by, n] of byPkg) ctx.log(`  \xB7 \uD328\uD0A4\uC9C0 ${by} \uAC00 \uC0DD\uC131\uD55C \uAC83 ${n}\uAC1C\uB294 \uB2F4\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4`);
+  if (c.notInProfile.length) ctx.log(`\uCC3D\uACE0\uC5D0\uB294 \uC788\uC9C0\uB9CC \uD504\uB85C\uD544 "${profile}" \uC774 \uC548 \uC4F0\uB294 \uAC83 ${c.notInProfile.length}\uAC1C: ${c.notInProfile.join(", ")}  \u2192 lshed.yaml \uC758 profiles \uC5D0 \uCD94\uAC00`);
+}
+
 // src/core/status.ts
 async function status(ctx) {
   const state = await readState(ctx.adapter);
-  if (!state) return { state: null, drifted: [], packages: [], missingEnv: [] };
+  if (!state) return { state: null, drifted: [], packages: [], missingEnv: [], fresh: [] };
   const d = await diff(ctx);
   const m = await loadManifest(ctx);
   const lock = await readLock(ctx.shed);
@@ -1274,7 +1383,8 @@ async function status(ctx) {
     const missing = shed === null ? [] : expand(shed).missing;
     if (missing.length) missingEnv.push({ rel: it.rel, vars: missing });
   }
-  return { state, drifted: d.map((x2) => `${x2.item.category}/${x2.item.id}`), packages, missingEnv };
+  const fresh = (await candidates(ctx, m, state.profile)).fresh.map(keyOf);
+  return { state, drifted: d.map((x2) => `${x2.item.category}/${x2.item.id}`), packages, missingEnv, fresh };
 }
 function formatStatus(s, adapterRoot) {
   if (!s.state) return `\uC801\uC6A9\uB41C \uD504\uB85C\uD544\uC774 \uC5C6\uC2B5\uB2C8\uB2E4 (${adapterRoot}).
@@ -1292,6 +1402,7 @@ function formatStatus(s, adapterRoot) {
     lines.push(`\uD328\uD0A4\uC9C0   ${p.pkg.id}  ${where}`);
   }
   for (const m of s.missingEnv) lines.push(`\uD658\uACBD\uBCC0\uC218 ${m.rel}: ${m.vars.join(", ")} \uC5C6\uC74C  \u2192 \uC178\uC5D0\uC11C export \uD558\uC138\uC694`);
+  if (s.fresh.length) lines.push(`\uCC3D\uACE0 \uBC16  ${s.fresh.length}\uAC1C: ${s.fresh.join(", ")}  \u2192 lshed add`);
   return lines.join("\n");
 }
 
@@ -1371,9 +1482,9 @@ function formatRows(rows, m) {
 }
 
 // src/core/remove.ts
-import { promises as fs13 } from "fs";
-import path16 from "path";
-import YAML3, { isSeq, isMap } from "yaml";
+import { promises as fs14 } from "fs";
+import path18 from "path";
+import YAML6, { isSeq as isSeq2, isMap as isMap2 } from "yaml";
 function resolveKey(m, raw) {
   const rows = listRows(m);
   const [a, b] = raw.includes("/") ? raw.split("/", 2) : [void 0, raw];
@@ -1387,13 +1498,13 @@ async function remove(ctx, raw) {
   const { category, id } = resolveKey(m, raw);
   const users = listRows(m).find((r) => r.category === category && r.id === id).usedBy;
   if (users.length) throw new Error(`${category}/${id} \uB294 \uD504\uB85C\uD544 ${users.join(", ")} \uC774 \uC4F0\uACE0 \uC788\uC2B5\uB2C8\uB2E4. \uBA3C\uC800 \uD504\uB85C\uD544\uC5D0\uC11C \uBE7C\uC138\uC694.`);
-  const text = await fs13.readFile(manifestPath(ctx), "utf8");
-  const doc = YAML3.parseDocument(text);
+  const text = await fs14.readFile(manifestPath(ctx), "utf8");
+  const doc = YAML6.parseDocument(text);
   let deleted;
   if (category === PACKAGES) {
     const seq = doc.get(PACKAGES);
-    if (!isSeq(seq)) throw new Error("packages \uAC00 \uBAA9\uB85D\uC774 \uC544\uB2D9\uB2C8\uB2E4");
-    const idx = seq.items.findIndex((it) => isMap(it) && it.get("id") === id);
+    if (!isSeq2(seq)) throw new Error("packages \uAC00 \uBAA9\uB85D\uC774 \uC544\uB2D9\uB2C8\uB2E4");
+    const idx = seq.items.findIndex((it) => isMap2(it) && it.get("id") === id);
     seq.delete(idx);
     if (!seq.items.length) doc.delete(PACKAGES);
     const lock = await readLock(ctx.shed);
@@ -1404,19 +1515,19 @@ async function remove(ctx, raw) {
     ctx.log(`  - package ${id}  (\uB9E4\uB2C8\uD398\uC2A4\uD2B8\xB7\uB77D\uC5D0\uC11C \uC81C\uAC70. \uB85C\uCEEC clone \uC740 \uADF8\uB300\uB85C)`);
   } else {
     const seq = doc.getIn(["components", category]);
-    if (!isSeq(seq)) throw new Error(`components.${category} \uAC00 \uBAA9\uB85D\uC774 \uC544\uB2D9\uB2C8\uB2E4`);
-    const idx = seq.items.findIndex((it) => isMap(it) && it.get("id") === id);
+    if (!isSeq2(seq)) throw new Error(`components.${category} \uAC00 \uBAA9\uB85D\uC774 \uC544\uB2D9\uB2C8\uB2E4`);
+    const idx = seq.items.findIndex((it) => isMap2(it) && it.get("id") === id);
     seq.delete(idx);
     if (!seq.items.length) doc.deleteIn(["components", category]);
     const src = sourcePath(ctx, category, findComponent(m, category, id));
-    const inside = !path16.relative(ctx.shed, src).startsWith("..");
+    const inside = !path18.relative(ctx.shed, src).startsWith("..");
     if (inside && await exists(src)) {
       await removeTree(src);
       deleted = src;
     }
     ctx.log(`  - ${category}/${id}${deleted ? "" : "  (\uCC3D\uACE0 \uBC16 \uACBD\uB85C\uB77C \uD30C\uC77C\uC740 \uB450\uC5C8\uC74C)"}`);
   }
-  await fs13.writeFile(manifestPath(ctx), doc.toString());
+  await fs14.writeFile(manifestPath(ctx), doc.toString());
   return { category, id, deleted };
 }
 async function prune(ctx, opts = {}) {
@@ -1441,21 +1552,105 @@ ${removed.length}\uAC1C \uC81C\uAC70. \uCC3D\uACE0\uB97C \uCEE4\uBC0B\uD558\uC13
   return removed;
 }
 
+// src/core/sync.ts
+import os2 from "os";
+async function sync(ctx, opts = {}) {
+  const shed = ctx.shed;
+  const push = opts.push ?? true;
+  if (!await isRepo(shed)) {
+    throw new Error(`\uCC3D\uACE0\uAC00 git \uC800\uC7A5\uC18C\uAC00 \uC544\uB2D9\uB2C8\uB2E4: ${shed}
+  cd ${shed} && git init && git add -A && git commit -m "my harness"
+  \uC6D0\uACA9\uC5D0 \uB450\uB824\uBA74: git remote add origin <url> && git push -u origin HEAD`);
+  }
+  const res = { committed: [], pulled: 0, pushed: false, unsaved: [] };
+  if (await readState(ctx.adapter)) {
+    try {
+      res.unsaved = (await diff(ctx)).map((d) => `${d.item.category}/${d.item.id}`);
+    } catch {
+    }
+    if (res.unsaved.length) ctx.log(`  ! \uB85C\uCEEC \uD3B8\uC9D1 ${res.unsaved.length}\uAC1C\uAC00 \uCC3D\uACE0\uC5D0 \uC5C6\uC2B5\uB2C8\uB2E4: ${res.unsaved.join(", ")}  \u2192 lshed save \uD6C4 \uB2E4\uC2DC sync`);
+  }
+  const dirty = (await git(["status", "--porcelain", "--untracked-files=all"], shed)).split("\n").filter(Boolean).map((l) => l.slice(3).trim());
+  if (dirty.length) {
+    const msg = opts.message ?? defaultMessage(dirty, (await readState(ctx.adapter))?.profile);
+    ctx.log(`  ${opts.dryRun ? "(dry-run) " : ""}commit ${dirty.length}\uAC1C: ${dirty.slice(0, 5).join(", ")}${dirty.length > 5 ? ` \uC678 ${dirty.length - 5}` : ""}`);
+    if (!opts.dryRun) {
+      await git(["add", "-A"], shed);
+      await git(["commit", "--quiet", "-m", msg], shed);
+    }
+    res.committed = dirty;
+  } else {
+    ctx.log("  = \uCC3D\uACE0\uC5D0 \uCEE4\uBC0B\uD560 \uBCC0\uACBD \uC5C6\uC74C");
+  }
+  const remote = await git(["remote", "get-url", "origin"], shed).catch(() => null);
+  if (!remote) {
+    ctx.log("  \xB7 origin \uC774 \uC5C6\uC5B4 pull/push \uB294 \uAC74\uB108\uB700 (git remote add origin <url>)");
+    return res;
+  }
+  if (opts.dryRun) {
+    ctx.log(`  (dry-run) pull --rebase, push \u2192 ${remote}`);
+    return res;
+  }
+  const before = await git(["rev-parse", "HEAD"], shed);
+  const branch2 = await git(["rev-parse", "--abbrev-ref", "HEAD"], shed);
+  const hasUpstream = await git(["rev-parse", "--abbrev-ref", "@{upstream}"], shed).then(() => true, () => false);
+  if (hasUpstream) {
+    try {
+      await git(["pull", "--rebase", "--quiet"], shed);
+    } catch (e) {
+      await git(["rebase", "--abort"], shed).catch(() => {
+      });
+      throw new Error(`pull \uC911 \uCDA9\uB3CC\uC774 \uB098\uC11C \uB418\uB3CC\uB838\uC2B5\uB2C8\uB2E4. \uCC3D\uACE0\uC5D0\uC11C \uC9C1\uC811 \uD574\uACB0\uD558\uC138\uC694:
+  cd ${shed} && git pull --rebase
+  (${firstLine(e.message)})`);
+    }
+    const after = await git(["rev-parse", "HEAD"], shed);
+    if (after !== before) {
+      const n = Number(await git(["rev-list", "--count", `${before}..${after}`], shed).catch(() => "0"));
+      res.pulled = Math.max(0, n - (res.committed.length ? 1 : 0));
+      if (res.pulled) ctx.log(`  \u2193 \uC6D0\uACA9 \uCEE4\uBC0B ${res.pulled}\uAC1C \uBC1B\uC74C`);
+    }
+  } else {
+    ctx.log(`  \xB7 \uBE0C\uB79C\uCE58 ${branch2} \uC5D0 upstream \uC774 \uC5C6\uC5B4 pull \uC740 \uAC74\uB108\uB700`);
+  }
+  if (push) {
+    const ahead = hasUpstream ? Number(await git(["rev-list", "--count", "@{upstream}..HEAD"], shed)) : 1;
+    if (ahead > 0) {
+      await git(hasUpstream ? ["push", "--quiet"] : ["push", "--quiet", "-u", "origin", branch2], shed);
+      res.pushed = true;
+      ctx.log(`  \u2191 push ${hasUpstream ? `${ahead}\uAC1C \uCEE4\uBC0B` : `(upstream \uC124\uC815: origin/${branch2})`}`);
+    } else {
+      ctx.log("  = \uC6D0\uACA9\uACFC \uAC19\uC74C");
+    }
+  }
+  if (res.pulled) ctx.log(`
+\uCC3D\uACE0\uAC00 \uBC14\uB00C\uC5C8\uC2B5\uB2C8\uB2E4. \uC774 \uAE30\uAE30\uC5D0 \uC801\uC6A9\uD558\uB824\uBA74: lshed restore`);
+  return res;
+}
+function defaultMessage(paths, profile) {
+  const parts = [...new Set(paths.map((p) => p.split("/").slice(0, 2).join("/")))];
+  const head2 = parts.slice(0, 3).join(", ") + (parts.length > 3 ? ` +${parts.length - 3}` : "");
+  return `lshed sync: ${head2}
+
+${os2.hostname()}${profile ? ` \xB7 profile ${profile}` : ""}`;
+}
+var firstLine = (s) => s.split("\n").find((l) => l.trim() && !l.startsWith("Command failed")) ?? s;
+
 // src/cli.ts
 var { version } = createRequire(import.meta.url)("../package.json");
 var program = new Command().name("lshed").description("Keep your coding-agent harness (skills, agents, commands, instructions) in a shed and restore it anywhere by profile.").version(version).option("--shed <dir>", "shed directory (default: $LSHED_HOME, then the shed recorded by the last restore)").option("--root <dir>", "agent config root (default: ~/.claude)");
 function adapterFromOpts() {
   const { root } = program.opts();
-  return new ClaudeCodeAdapter(root ? path17.resolve(root) : void 0);
+  return new ClaudeCodeAdapter(root ? path19.resolve(root) : void 0);
 }
 async function ctxFor(cmd) {
   const adapter = adapterFromOpts();
   const { shed: flag } = program.opts();
   let shed = flag ?? process.env.LSHED_HOME;
   if (!shed && cmd === "other") shed = (await readState(adapter))?.shed;
-  if (!shed && cmd === "init") shed = path17.join(os2.homedir(), "lshed");
+  if (!shed && cmd === "init") shed = path19.join(os3.homedir(), "lshed");
   if (!shed) throw new Error("\uCC3D\uACE0 \uC704\uCE58\uB97C \uBAA8\uB985\uB2C8\uB2E4. --shed <dir> \uB610\uB294 LSHED_HOME \uC744 \uC9C0\uC815\uD558\uC138\uC694.");
-  return { adapter, shed: path17.resolve(shed), log: (l) => console.log(l), exec: spawnExec };
+  return { adapter, shed: path19.resolve(shed), log: (l) => console.log(l), exec: spawnExec };
 }
 async function run(fn) {
   try {
@@ -1500,7 +1695,7 @@ program.command("status").description("show the applied profile, managed paths a
   const adapter = adapterFromOpts();
   const state = await readState(adapter);
   if (!state) {
-    console.log(formatStatus({ state: null, drifted: [], packages: [], missingEnv: [] }, adapter.root));
+    console.log(formatStatus({ state: null, drifted: [], packages: [], missingEnv: [], fresh: [] }, adapter.root));
     return;
   }
   const ctx = await ctxFor("other");
@@ -1514,6 +1709,14 @@ program.command("save [ids...]").description("copy local edits back into the she
   const ctx = await ctxFor("other");
   await save(ctx, ids);
 }));
+program.command("add [keys...]").description("put things that appeared locally since init into the shed and the current profile (lists candidates without keys)").option("--all", "add every candidate").action((keys, o) => run(async () => {
+  const ctx = await ctxFor("other");
+  await add(ctx, keys, { all: o.all });
+}));
+program.command("sync").description("commit the shed, pull --rebase and push (the shed must be a git repo with origin)").option("-m, --message <msg>", "commit message (default: names the changed parts)").option("--no-push", "commit and pull only").option("--dry-run", "show what would be committed and pushed").action((o) => run(async () => {
+  const ctx = await ctxFor("other");
+  await sync(ctx, { message: o.message, push: o.push, dryRun: o.dryRun });
+}));
 program.command("list").description("everything in the shed and which profiles use it").option("--unused", "only things no profile uses").action((o) => run(async () => {
   const ctx = await ctxFor("other");
   const m = await loadManifest(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lshed",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Portable harness environment manager for coding agents",
   "license": "MIT",
   "author": "leesongheon <leesongheon1209@gmail.com>",