docs + CLAUDE.md: reflect plugin marketplace install model

Updates every doc surface that described the old `lc init` behavior
(copy bundle subdirs into project `.claude/`) to match the new install
flow (`claude plugin marketplace add` + `claude plugin install
lightcone@lightcone-cli`).

Touched:
- docs/index.md, docs/architecture.md, docs/contributing/setup.md,
  docs/skills/index.md — show the new wheel layout (the repo-root
  `.claude-plugin/marketplace.json` plus `claude/lightcone/.claude-plugin/
  plugin.json`); describe `get_marketplace_root()` (replaces
  `get_plugin_source_dir`); update the force-include block to include
  the marketplace manifest.
- docs/cli/init.md — describe what `lc init` writes (just the
  permissions tier) and what it shells out for (the plugin install,
  idempotent, soft-fail when claude CLI is missing).
- docs/cli/update.md, docs/skills/authoring.md — replace the old
  `shutil.copytree(get_plugin_source_dir(), …)` recipes with
  `claude plugin marketplace add` + `claude plugin install` flows.
- docs/skills/ralph.md — switch the launcher path to
  `${CLAUDE_PLUGIN_ROOT}/skills/ralph/scripts/ralph`.
- docs/user/getting-started.md, docs/user/troubleshooting.md —
  user-facing description of what lives in the project's `.claude/`
  (just `settings.json`) vs. what's user-scoped under `~/.claude/`
  (the plugin itself).
- CLAUDE.md — refresh the Repository Structure block to show the new
  manifest files and the renamed `get_marketplace_root` constant.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
(cherry picked from commit 659278f)

Author: cailmdaley

CLAUDE.md

@@ -50,7 +50,7 @@ src/lightcone/              # namespace — NO __init__.py
 ├── cli/                    # Click surface
 │   ├── __init__.py         # exposes main()
 │   ├── commands.py         # init, run, status, verify, build
-│   ├── plugin.py           # get_plugin_source_dir
+│   ├── plugin.py           # get_marketplace_root + MARKETPLACE_NAME / PLUGIN_NAME constants
 │   └── claude/             # force-included Claude plugin bundle (in installed wheel only)
 ├── engine/                 # execution substrate — Snakemake-based
 │   ├── __init__.py
@@ -66,17 +66,23 @@ src/lightcone/              # namespace — NO __init__.py
     ├── cli.py              # `lc eval` subcommand group
     ├── harness.py, sandbox.py, graders.py, build.py, report.py, models.py
 
-claude/lightcone/           # Claude plugin source — force-included into the wheel
+.claude-plugin/             # marketplace manifest (force-included into the wheel)
+└── marketplace.json        # declares the `lightcone` plugin sourced from ./claude/lightcone
+
+claude/lightcone/           # Claude Code plugin source — force-included into the wheel
+├── .claude-plugin/plugin.json  # plugin manifest (name=lightcone)
 ├── skills/                 # lc-new, lc-from-code, lc-from-paper,
 │                            # lc-feedback, ralph;
 │                            # paper-reproduction bundle: lc-from-paper (entry),
 │                            # ralph (loop substrate), narrative,
 │                            # paper-extraction, figure-comparison,
 │                            # check-sentence-by-sentence
+│                            # plus reference skills astra, lc-cli
 │                            # (see skills/README.md for the full bundle map)
 ├── agents/                 # lc-extractor
-├── templates/              # Project CLAUDE.md template
-└── scripts/                # Session hooks (bash): venv activation, validate-on-save, session-start primer
+├── hooks/hooks.json        # hook config (${CLAUDE_PLUGIN_ROOT}-rooted commands)
+├── scripts/                # hook handlers (bash): activate-venv, session-start primer, validate-on-save
+└── templates/              # Project CLAUDE.md template
 
 tests/                      # pytest — mirrors src/ structure
 pyproject.toml              # hatchling + hatch-vcs, ASTRA + Snakemake as deps

docs/architecture.md

@@ -236,31 +236,44 @@ the qualified `<analysis_id>.<output_id>` form.
 
 ## Claude Code plugin
 
-The plugin lives at `claude/lightcone/`. It is force-included into the
-installed wheel via `pyproject.toml` so `lc init` can find it whether
-you're running from source or from PyPI:
+The bundle at `claude/lightcone/` is a proper Claude Code plugin: manifest at
+`claude/lightcone/.claude-plugin/plugin.json`, hooks at
+`claude/lightcone/hooks/hooks.json` (with command paths rooted at
+`${CLAUDE_PLUGIN_ROOT}`), plus the skill / agent / script subdirectories.
+The repo root carries a `.claude-plugin/marketplace.json` declaring one
+plugin (`lightcone`) sourced from `./claude/lightcone`.
+
+Both directories are force-included into the wheel so `lc init` finds the
+marketplace whether you're running from source or from PyPI:
 
 ```toml
 [tool.hatch.build.targets.wheel.force-include]
 "claude/lightcone" = "lightcone/cli/claude/lightcone"
+".claude-plugin/marketplace.json" = "lightcone/cli/.claude-plugin/marketplace.json"
 ```
 
-`lightcone.cli.plugin.get_plugin_source_dir()` does the lookup: bundled
-location first, dev location (relative to the repo root) second.
+`lightcone.cli.plugin.get_marketplace_root()` does the lookup — it returns
+the directory containing `.claude-plugin/marketplace.json` (the wheel-
+installed package root, or in dev the repo root). `lc init` shells out to
+`claude plugin marketplace add <root>` then `claude plugin install
+lightcone@lightcone-cli`. Both Claude CLI calls are idempotent.
 
 ### Permission tiers
 
 `lc init --permissions {yolo,recommended,minimal}` writes a
 `.claude/settings.json` from the matching tier in
 `PERMISSION_TIERS`. `recommended` (the default) allows the agent to
 edit, write, and shell out, but blocks edits to dotfiles, scratch
-paths, and `git push`.
+paths, and `git push`. This is the only thing `lc init` writes into
+the project's `.claude/` — the plugin (skills, agents, hooks) lives
+user-scoped under `~/.claude/plugins/`, not duplicated per project.
 
 ### Hooks
 
 The plugin registers Claude Code hooks for venv activation,
-auto-validation on save, and integrity-aware "did you forget `lc run`?"
-warnings.
+auto-validation on save, and surfacing materialization status at session
+start. Hook scripts live at `${CLAUDE_PLUGIN_ROOT}/scripts/` and the
+matchers/timeouts are declared in `claude/lightcone/hooks/hooks.json`.
 
 ---
 

docs/cli/init.md

@@ -22,12 +22,25 @@ CLAUDE.md                     # short note pointing future agents at the project
   lightcone.yaml              # currently a stub: { target: local }
 results/                      # placeholder; populated by `lc run`
 universes/                    # placeholder; populate via `astra universe generate -n …`
-.claude/                      # bundled Claude Code plugin
-  skills/, agents/, hooks/, scripts/, templates/
-  settings.json               # the chosen permission tier
+.claude/
+  settings.json               # the chosen permission tier (project-scoped)
 .venv/                        # Python venv (skipped with --no-venv)
 ```
 
+`lc init` then shells out to the `claude` CLI (if found on PATH) to install
+the `lightcone` plugin into the user's Claude Code config:
+
+```
+claude plugin marketplace add <wheel-installed marketplace root>
+claude plugin install lightcone@lightcone-cli
+```
+
+The plugin (skills, agents, hooks) lives user-scoped under `~/.claude/`, not
+per-project. Both commands are idempotent, so subsequent `lc init` calls are
+no-ops for the plugin. When `claude` isn't on PATH (Codex users, etc.), the
+plugin install is skipped and the manual commands above are printed — `lc init`
+still succeeds.
+
 `lc init` refuses to run if `DIRECTORY/astra.yaml` already exists.
 
 ## Options

docs/cli/update.md

@@ -7,26 +7,19 @@ tooling:
 pip install --upgrade lightcone-cli       # or: uv pip install -U lightcone-cli
 ```
 
-To pull updated plugin files into an existing project (`lc init` refuses to
-run if `astra.yaml` already exists, so we copy by hand):
+The lightcone plugin (skills, agents, hooks) lives user-scoped under
+`~/.claude/plugins/` — installed once by `lc init` via `claude plugin
+install lightcone@lightcone-cli`, not duplicated per project. To pull in
+plugin changes after a `pip install --upgrade`:
 
 ```bash
-python - <<'PY'
-import shutil
-from pathlib import Path
-from lightcone.cli.plugin import get_plugin_source_dir
-
-src = get_plugin_source_dir()
-dst = Path(".claude")
-for sub in ("skills", "agents", "scripts", "guides", "templates"):
-    s, d = src / sub, dst / sub
-    if d.exists():
-        shutil.rmtree(d)
-    if s.exists():
-        shutil.copytree(s, d)
-print("synced from", src)
-PY
+# Re-register the marketplace at its new wheel-installed location, then
+# re-install the plugin so Claude Code reads from the updated source.
+python -c "from lightcone.cli.plugin import get_marketplace_root; print(get_marketplace_root())" \
+    | xargs claude plugin marketplace add
+claude plugin install lightcone@lightcone-cli
 ```
 
-A short `bin/lc-sync` helper or a `lc init --sync` flag would make this
-nicer — see the issue tracker if interested.
+Both commands are idempotent. `claude plugin marketplace remove
+lightcone-cli` then `add` again is the heaviest hammer, and rarely
+necessary.

docs/contributing/setup.md

@@ -61,26 +61,34 @@ just build              # uv build
 just version            # current version (from git tags via hatch-vcs)
 ```
 
-The plugin (`claude/lightcone/`) is force-included into the wheel:
+The plugin (`claude/lightcone/`) and the repo-root marketplace manifest
+(`.claude-plugin/marketplace.json`) are both force-included into the wheel:
 
 ```toml
 [tool.hatch.build.targets.wheel]
 packages = ["src/lightcone", "src/snakemake_executor_plugin_dask"]
 
 [tool.hatch.build.targets.wheel.force-include]
 "claude/lightcone" = "lightcone/cli/claude/lightcone"
+".claude-plugin/marketplace.json" = "lightcone/cli/.claude-plugin/marketplace.json"
 ```
 
-That layout is what `lightcone.cli.plugin.get_plugin_source_dir()`
-walks — it tries the bundled location first, then the dev location
-relative to the repo root.
+That layout is what `lightcone.cli.plugin.get_marketplace_root()` walks —
+it returns the directory containing `.claude-plugin/marketplace.json` (the
+wheel-installed package root in a normal install, or the dev repo root
+when running from a checkout). `lc init` shells out to
+`claude plugin marketplace add <root>` and `claude plugin install
+lightcone@lightcone-cli` against that root.
 
 ## Repo layout
 
 ```text
 src/lightcone/                       # main namespace (PEP 420; no __init__.py at the package root)
 src/snakemake_executor_plugin_dask/  # Snakemake → Dask executor plugin
+.claude-plugin/marketplace.json      # marketplace manifest (force-included into the wheel)
 claude/lightcone/                    # Claude Code plugin (force-included into the wheel)
+  .claude-plugin/plugin.json         #   plugin manifest
+  skills/  agents/  hooks/  scripts/  templates/
 tests/                               # pytest tree, mirrors src/
 evals/                               # eval task fixtures (tasks/snae/)
 docs/                                # docs site

docs/index.md

@@ -71,13 +71,18 @@ src/lightcone/                  # PEP 420 namespace package — NO __init__.py
 
 src/snakemake_executor_plugin_dask/   # Snakemake executor → dask.distributed
 
+.claude-plugin/                 # marketplace manifest (force-included into the wheel)
+└── marketplace.json            # declares the `lightcone` plugin sourced from ./claude/lightcone
+
 claude/lightcone/               # Claude Code plugin (force-included into the wheel)
+├── .claude-plugin/plugin.json  # plugin manifest
 ├── skills/                     # lc-new, lc-from-code, lc-from-paper,
 │                                # lc-feedback, ralph (+ bundle siblings);
 │                                # reference skills: astra, lc-cli
 ├── agents/                     # lc-extractor (literature subagent)
-├── templates/                  # project CLAUDE.md template
-└── scripts/                    # session hooks (bash): venv, validate-on-save, session-start primer
+├── hooks/hooks.json            # hook config (${CLAUDE_PLUGIN_ROOT}-rooted commands)
+├── scripts/                    # hook scripts: venv, validate-on-save, session-start primer
+└── templates/                  # project CLAUDE.md template
 
 tests/                          # pytest, mirrors src/
 pyproject.toml                  # hatchling + hatch-vcs; ASTRA + Snakemake as deps

docs/skills/authoring.md

@@ -7,7 +7,7 @@ Skills are markdown files with YAML frontmatter. Each one lives in
 
 ## File layout
 
-```text
+```
 claude/lightcone/skills/
 └── my-skill/
     ├── SKILL.md
@@ -40,9 +40,9 @@ argument-hint: "[OPTIONAL ARG] [--flag VALUE]"
 
 - `##` for phase headings; lead with a "Stage banner" line that the
   skill prints to the chat.
-- `✓ / ○ / ✗` for status. Skip emoji elsewhere — they belong only
-  inside the agent's own branded banner output.
-- Action prompts in blockquotes (`> "What are you trying to learn?"`).
+- `✓ / ○ / ✗` for status; never emojis except inside the agent's own
+  branded output.
+- Action prompts in bold sentences (`> "What are you trying to learn?"`).
 - A `## Restrictions` (or `## Hard rules`) section at the end listing
   invariants Claude must not break.
 
@@ -62,7 +62,7 @@ call when a specific section is load-bearing for that skill's work.
 
 ## Spawning subagents
 
-Use `Agent` with `subagent_type` to delegate work. The
+Use `Task` with `subagent_type` to delegate work. The
 `lc-extractor` subagent in `agents/` is the canonical example:
 
 ```python
@@ -90,9 +90,21 @@ from lightcone.eval.cli import run_cmd
 # or invoke `lightcone.eval.harness.run_eval(...)` directly
 ```
 
-## Installing changes into an existing project
+## Picking up edits during development
+
+The `lightcone` plugin lives user-scoped under `~/.claude/plugins/`, installed
+via `claude plugin install lightcone@lightcone-cli`. When you're working
+inside a `lightcone-cli` checkout and want Claude Code to pick up your
+edits, register the marketplace from the repo root (it takes precedence
+over any other registration of the same name):
+
+```bash
+claude plugin marketplace add /path/to/lightcone-cli
+claude plugin install lightcone@lightcone-cli
+```
+
+Restart Claude Code; the plugin now loads from your checkout's
+`claude/lightcone/` directly. Edits to `SKILL.md` files take effect on
+the next session start.
 
-`lc init` copies the plugin once and refuses to run a second time on
-the same directory. See [Updating an existing project](../cli/update.md)
-for the Python heredoc that resyncs all the plugin subdirs (`skills`,
-`agents`, `scripts`, `guides`, `templates`) into an existing project.
+(See [`lc update`](../cli/update.md) for the upgrade-from-PyPI story.)