Plugin distribution, contributor-facing READMEs, and site event tracking

[krayong]

Prepares the repo for launch week. Three strands, independent of each other: a Claude Code plugin so ccsidekick is discoverable from inside the product, a contributor funnel visible to someone who has not already decided to contribute, and real event instrumentation on the landing site.

Nothing here changes the render or classify hot path, and no telemetry is added to the CLI.

1. Plugin distribution

Adds .claude-plugin/plugin.json and .claude-plugin/marketplace.json, so the repo is both a plugin and its own single-plugin marketplace:

/plugin marketplace add krayong/ccsidekick
/plugin install ccsidekick@ccsidekick

The plugin ships no hooks, deliberately. A plugin cannot set the main statusLine (bundled plugin settings support only agent and subagentStatusLine), so every plugin user runs the npm installer anyway, and that installer already registers both classify hooks. Shipping hooks too would register them twice. appendEvent has no dedupe key, so every mood, streak and familiarity tier would read a doubled event log. There is also no binary to run: packages/core/dist/ is gitignored build output.

commands/ccsidekick-setup.md closes the gap that leaves, with a /ccsidekick-setup command driving npx ccsidekick setup across the whole flag surface. Two flags keep guardrails rather than bans, because both surprise people:

• --widgets replaces the enabled set rather than adding to it, so the command reads the current config before changing it.
• --usage-fetch=on starts sending an OAuth token to Anthropic, so it needs an explicit yes first.

--config-dir stays refused: no path validation, and it redirects where settings.json is written. The command's Bash grant is scoped to Bash(npx -y ccsidekick:*) rather than bare npx, so it cannot pre-approve fetching an arbitrary package.

Only plugin.json carries a version. claude plugin validate --strict needs the marketplace's own name, owner and description plus each entry's name and source, and nothing else, so every other field on the entry would be a duplicate free to drift. scripts/sync-plugin-version.ts keeps it in step inside ci:version, by targeted string replacement rather than parse-and-reserialize: JSON.stringify re-expands arrays Prettier keeps inline, which would fail format:check on every release PR.

No CI gate runs claude plugin validate. It resolves latest over the network on a required check, so an upstream release could block every merge with nothing in the diff, and it was measured not to read plugin.json at all (deleting that file still exits 0). scripts/plugin-manifest.test.ts gates it offline instead: version parity, name/source agreement, the absence of a second version, the description match, and the single-occurrence invariant the string replacement depends on.

2. Contributor funnel

Pack authoring lived under a level-three heading in Development pointing at an internal skill path. Nobody deciding whether to contribute ever scrolled that far. It is now a top-level Author your own character section in both READMEs, with the figure budget, the voice-pool floor, the lint gate, and where to start.

packages/core/README.md was a 3.5 KB stub, and it is the page every npm visitor lands on. It gains the reel, the eighteen-pack roster, the authoring invitation, and a watch-for-releases line, with every link and image absolute so npm renders them.

readme-drift.ts guarded the root README alone, so the npm page's counts and roster could rot silently. It now checks both.

3. Site event tracking

Cloudflare Web Analytics does not support custom events, so scripts/website/worker.ts adds a same-origin POST /e sink writing one Workers Analytics Engine data point per event. The site stops being assets-only: wrangler.jsonc gains main, an ASSETS binding, and run_worker_first: ["/e"] so every other path keeps asset-first behaviour.

The endpoint is public and unauthenticated, so it checks Origin, rejects on Content-Length before reading any body (Cloudflare allows 100 MB into a 128 MB isolate), and accepts only four names from a closed set. scripts/website/worker.test.ts covers it in 19 cases; with no preview URL and no staging origin, those tests are the only exercise the code gets before production.

deploy.yml's cache key hashed website/ alone, which described the deploy completely while the site was assets-only. It now includes wrangler.jsonc and the Worker. Without that, any Worker-only change — including the documented rollback that removes main — would produce an identical tree, skip wrangler deploy, and report green.

Also fixed

• The README's releases CTA pointed at /subscriptions, which 404s. The path is singular.
• Both READMEs claimed the pack-author skill loads itself when you open Claude Code. It does not.
• CLAUDE.md, website/CLAUDE.md and wrangler.jsonc all still described an assets-only site. They are how the next session learns the architecture, and an agent reading them could reasonably delete main as dead config.

Verification

All green on bf7450d:

Check	Result
format:check / lint / typecheck	exit 0
bun run test	1100 pass, 0 fail
readme:drift	33 widgets, 75 themes (floor 75+), 18 packs
site:build	ok
claude plugin validate ./ --strict	✔ Validation passed
changeset status --since=main	patch bump for ccsidekick
wrangler@4.110.0 deploy --dry-run	bundles; resolves env.EVENTS and env.ASSETS

The drift guard was checked in both directions: it catches a genuinely missing pack and a stale widget count, and passes clean on the real tree.

Before this goes live

Merging is safe on its own. The event sink only becomes reachable when someone dispatches the deploy, which is workflow_dispatch-only and does not fire on merge.

• Cloudflare Rate Limiting rule on /e — deployed. Free plan: path /e, characteristic IP, 10 req / 10 s, Block, 10 s.
• Confirm Analytics Engine is enabled on the account. If it is not, wrangler deploy fails. Deploys are atomic, so the live site is unaffected by that failure.
• Dispatch deploy.yml, then verify POST /e with the correct Origin returns 204. It returns 405 today from the assets layer, so 405 after deploy means run_worker_first did not take effect.
• Diff the security headers before and after: _headers does not apply to Worker-generated responses.

Note on quota: static asset requests are free and unlimited and never invoke the Worker, so only /e consumes the Workers free tier. If that is exhausted, /e returns 429 and the landing page keeps serving normally.

🦇 Generated by Penny-One at Batcave