docs: clarify setup, contributor checks, and troubleshooting

CONTRIBUTING.md

@@ -26,16 +26,47 @@ Codex** from a single repo. Contributions must keep both harnesses correct.
   `version` (the Codex manifest may carry a `+codex.<build>` metadata suffix; the
   base semver must match). The validator enforces this.
 
+## Current CI checks
+
+Run the [workflow's](.github/workflows/ci.yml) command set from the repository root:
+
+```bash
+python3 scripts/validate.py
+python3 skills/skill-curator/scripts/curator.py selftest
+python3 scripts/score.py selftest
+python3 scripts/portfolio.py selftest
+python3 scripts/calibrate.py selftest
+python3 scripts/score.py . --min 70
+```
+
+The deterministic selftests use temporary fixtures. The final command checks the
+current repository against CI's score floor. Diagnostic warnings are advisory;
+validator error findings fail the run. See [troubleshooting](docs/troubleshooting.md)
+for finding codes and score-baseline caveats. For documentation changes, check
+relative links and verify every new command against its script's CLI parser.
+Report any checks you could not run and why.
+
 ## Installing locally
 
-Sync the repo into both harness plugin dirs with:
+After reviewing the helper, sync the source into Codex and install or refresh the
+Claude Code marketplace with:
 
 ```
 scripts/sync.sh
 ```
 
-This installs into `~/.codex/plugins/` and `~/.claude/plugins/` so you can exercise
-your changes in a real session on each harness.
+The helper uses `rsync --delete` to refresh `~/.codex/plugins/plugin-improver/`.
+It preserves excluded per-install bookkeeping such as `.plugin-improver` and
+`state.yaml`, but other destination files absent from the source can be removed.
+Do not keep independent edits in that destination.
+
+For Claude Code, it invokes the available `claude` CLI marketplace add/update and
+plugin install/update commands. Without the CLI it prints the interactive commands
+for you to run; it does not copy files directly into the Claude cache. Some
+marketplace operations tolerate failures, so the helper's final message alone
+does not prove both hosts installed successfully. Verify skills in a new session
+on each host. Codex marketplace registration remains a separate step from copying
+the source to disk; see [the README](README.md#codex).
 
 ## Pull requests
 
@@ -44,3 +75,4 @@ your changes in a real session on each harness.
   and configs depend on.
 - Keep the two manifest versions in agreement in the same PR that bumps either.
 - Author attribution is `RasputinKaiser` only.
+

README.md

@@ -4,6 +4,14 @@
 
 **A meta-plugin that audits, tunes, and evolves your other plugins — and curates your whole skill+plugin inventory — endlessly improvable, never regressing, never bloating context.**
 
+## Start here
+
+- [Install](#install) in Claude Code or Codex, then run an audit against a **source** plugin folder
+- [Usage](#usage) shows explicit invocation and a dependency-free CLI quick start
+- [Troubleshooting](docs/troubleshooting.md) covers discovery, install drift, validator findings, and score baselines
+- [Architecture](docs/architecture.md), [skill guides](docs/skills/), and [measurement roadmap](docs/ROADMAP-measurement-graph.md) explain the components
+- [Contributing](CONTRIBUTING.md), [changelog](CHANGELOG.md), and [ledger](LEDGER.md) provide development context
+
 ## What it is
 
 plugin-improver is a single plugin that runs on **both Claude Code and Codex** from one shared `skills/` tree. It gives plugin authors a disciplined loop for making plugins better: score a plugin's health, sharpen the descriptions that decide when its skills fire, repair its lifecycle hooks, run bounded improvement passes that are gated against regression, and widen the lens to the entire inventory to catch sprawl, collisions, and version drift. Two new skills round out the lifecycle: scaffolding a fresh dual-harness plugin, and packaging one for release to both marketplaces.
@@ -28,6 +36,18 @@ Every skill body, manifest, and doc here is written to be true on both harnesses
 - **Improvement without bloat.** Descriptions and skill bodies carry explicit context budgets; every added sentence must change agent behavior, and detail is pushed to `references/` for progressive disclosure.
 - **Per-plugin memory.** Each target plugin gets a `LEDGER.md` (decisions, with provenance) and a `.plugin-improver/baseline.json` (last score), so successive passes compound instead of relitigating.
 
+## Requirements and compatibility
+
+- Claude Code or Codex with plugin support for agent-driven skills
+- Python 3 for the bundled diagnostics, which use the standard library; CI uses a current `3.x` interpreter and this repository does not pin a minimum Python release
+- A POSIX shell and `rsync` for the optional local sync helper; the `claude` CLI enables its automatic Claude Code marketplace steps
+
+The current source manifests both declare **1.4.0**. Source version, installed
+cache version, and the version loaded by an open host session can differ.
+Codex consumes the shared skills plus `agents/openai.yaml`; Claude Code also has
+the `commands/` slash-command adapters. This repository's own Codex manifest
+declares skills, not an MCP server or lifecycle hooks.
+
 ## Install
 
 plugin-improver installs on either harness — or both — from this one repository.
@@ -65,14 +85,33 @@ You can also point the marketplace at a local clone:
 
 ## Usage
 
-Point any skill at a plugin folder and describe the goal:
+Point any skill at an editable **source** plugin folder containing a plugin manifest and describe the goal. Avoid installed copies under either harness's `plugins/cache/`:
 
 - "Audit the plugin in `~/.claude/plugins/my-plugin`."
 - "Improve my-plugin" — implicit invocation picks `plugin-improve`.
 - "Curate my skills and find version drift."
 
 Both harnesses auto-trigger skills from their descriptions. To invoke one explicitly, use the harness's own syntax: on Codex, `$plugin-improve`; on Claude Code, the matching slash command (`/plugin-improver:plugin-improve`, one per skill) or the Skill tool. The skill bodies are harness-neutral and branch only where the two genuinely diverge (hooks capabilities, feature flags, manifest paths).
 
+### CLI quick start
+
+You can inspect a plugin without installing plugin-improver in a host. Clone this
+repository and run these commands from its root, replacing `/path/to/my-plugin`
+with the source folder you want to inspect:
+
+```bash
+python3 scripts/validate.py /path/to/my-plugin
+python3 scripts/score.py /path/to/my-plugin --json
+python3 scripts/tokens.py /path/to/my-plugin
+```
+
+These commands inspect structure, deterministic score, and estimated context cost.
+They do not edit the target. The machine score leaves `needs_judgment` for a fuller
+audit; it is not a guarantee of runtime behavior. Token counts are estimates.
+`plugin-improve` is a separate agent-driven workflow that can edit the target,
+update its manifests, and write its ledger/baseline. Start with an audit when you
+want findings before changes.
+
 ## Development
 
 The repo self-validates with a stdlib-only Python script — no dependencies:
@@ -84,6 +123,12 @@ python3 scripts/validate.py --json   # machine-readable
 
 It checks that both manifests parse and agree, that every SKILL.md has valid frontmatter within its context budget, that every reference link resolves, that each skill ships its Codex `agents/openai.yaml`, and that the plugin is discoverable by both harnesses. CI runs it on every push and pull request (`.github/workflows/ci.yml`). See [`docs/architecture.md`](docs/architecture.md) for how one tree serves both harnesses, and [`docs/skills/`](docs/skills/) for one page per skill.
 
+For the complete current CI command set and local install caveats, see
+[CONTRIBUTING.md](CONTRIBUTING.md). Validator exit 0 means no error-severity
+findings; warnings can still be present. Inspect them rather than treating a zero
+exit status as proof that every aspect of the plugin is healthy.
+
 ## License
 
 MIT © [RasputinKaiser](https://github.com/RasputinKaiser)
+

docs/troubleshooting.md

@@ -0,0 +1,84 @@
+# plugin-improver troubleshooting
+
+Use an editable plugin source folder, not an installed copy under
+`~/.claude/plugins/cache/` or `~/.codex/plugins/cache/`. See
+[installation](../README.md#install) and [architecture](architecture.md).
+
+## Skills do not appear
+
+- Claude Code: confirm the `plugin-improver` marketplace is added and
+  `plugin-improver@plugin-improver` is installed, then refresh or restart the host
+- Codex: confirm the source folder contains `.codex-plugin/plugin.json` and
+  `skills/`, register its local marketplace entry, then install from that marketplace
+- After source updates, refresh the installed plugin and start a new session;
+  source version, cache version, and loaded session version can differ
+- For explicit invocation, use `$plugin-audit` on Codex or
+  `/plugin-improver:plugin-audit` on Claude Code, with your source folder as the target
+
+Copying files alone does not establish marketplace registration or live discovery.
+The plugin's own Codex manifest declares a skills surface; an absent
+plugin-improver MCP server is not an installation failure because none is declared.
+
+## The sync helper says it finished, but one host is stale
+
+[`scripts/sync.sh`](../scripts/sync.sh) copies the source into Codex using `rsync`
+and handles Claude Code through its marketplace CLI, or prints manual instructions
+when the CLI is absent. Several marketplace add/update calls tolerate errors;
+inspect output and verify in a new host session rather than relying on “Done.”
+
+The helper requires a POSIX shell and `rsync`. It uses `--delete` for non-excluded
+destination files, so do not keep independent changes in its Codex destination.
+Excluded bookkeeping such as `.plugin-improver` and `state.yaml` is protected.
+See [local development](../CONTRIBUTING.md#installing-locally) before running it.
+
+## Understand validator findings
+
+From the plugin-improver source root:
+
+```bash
+python3 scripts/validate.py /path/to/my-plugin --json
+```
+
+[`validate.py`](../scripts/validate.py) emits stable `PI-<letter><3 digits>`
+finding codes with severity, path, and a fix hint. Namespaces include manifests
+(`M`), skill frontmatter (`S`), body budget (`B`), references (`R`), Codex interface
+(`I`), commands (`C`), parity (`P`), hooks (`H`), assets (`A`), and MCP shape (`J`).
+
+- Exit 0: no error-severity findings; warnings and informational findings may remain
+- Exit 1: at least one check has an error
+- Exit 2: the target does not look like a plugin root
+
+Read the exact finding before changing anything. For example, `PI-M006` is
+manifest version disagreement, `PI-S005` is a description exceeding 400 characters,
+and `PI-R001` is an unresolved reference. The soft body limit warns above 600
+words; the hard limit fails above 1,500. A green validator proves structural
+checks, not correct runtime behavior or measured trigger accuracy.
+
+## A score or baseline gate is surprising
+
+```bash
+python3 scripts/score.py /path/to/my-plugin --json
+python3 scripts/tokens.py /path/to/my-plugin
+```
+
+[`score.py`](../scripts/score.py) reports deterministic evidence and outstanding
+`needs_judgment`; a fuller audit still requires judgment. Its effective score
+normalizes applicable machine-scored dimensions to 100. Token reports use
+estimates rather than tokenizer-exact counts.
+
+`score.py --min-baseline PATH` warns and skips regression comparison when the
+baseline is missing, unreadable, has no usable `total.auto`, or predates effective
+scoring. Exit 0 alone therefore does not prove that a baseline comparison occurred.
+Inspect stderr and the baseline schema. Use an explicit `--min N` floor when a
+numeric floor is what you intend to enforce. Current repository CI uses 70.
+
+Saving a baseline or running an agent-driven improvement pass changes files.
+Choose that separately from inspection, and preserve the target's provenance and
+decision history.
+
+## Share a useful issue
+
+Include the host, OS, Python version, plugin source commit, both manifest versions,
+sanitized command, exit status, and relevant finding codes. Note which tests ran
+and whether the problem is in source, an installed cache, or a loaded session.
+Do not post private session logs, credentials, or unsanitized home-directory paths.