skill: publish

Publish snappy-os (the npm bootstrap) to the npm registry. Bumps version, runs the contract lint, packs, publishes, tags git.

When to use

• Bootstrap script (bin/install.js) or the published package.json shape

changed and a new version of snappy-os on npm needs to ship so npx snappy-os picks up the change.

Inputs

• NPM_TOKEN in .env.cache - granular access token with bypass-2FA

enabled, scoped to the snappy-os package. Created at https://www.npmjs.com/settings/robertboulos/tokens.

• A clean working tree (no uncommitted changes outside package.json).

Action

1. Read NPM_TOKEN via state/lib/env.ts.
2. Bump package.json version per --bump flag (default patch).
3. Run npm run check (typecheck + lint + runtime drift check).
4. Run npm run contract:stub (13 assertions on the eval-endpoint contract).
5. npm publish --access public with the token written to a temp .npmrc

(never persisted to ~/.npmrc).

1. git tag v<new-version> and git push origin v<new-version>.
2. Append eval row to state/log/evals.ndjson.

Eval

Auto. Shape gate (eval row has score, run_id, skill: "publish", primary_issue null on success / failure mode on error) plus post-publish probe: fetch https://registry.npmjs.org/snappy-os/<new-version> and confirm version === <new-version>.

Sidecar

state/bin/publish-bootstrap.sh - see the script for exact behavior. Run with:

bash state/bin/publish-bootstrap.sh                  # patch bump (0.1.0 → 0.1.1)
bash state/bin/publish-bootstrap.sh --bump minor     # 0.1.0 → 0.2.0
bash state/bin/publish-bootstrap.sh --bump major     # 0.1.0 → 1.0.0
bash state/bin/publish-bootstrap.sh --dry            # everything except publish + tag

Failure modes

• NPM_TOKEN not set - print exact command to create granular token,

exit 2.

• Working tree dirty (outside package.json) - refuse, exit 3.
• npm run check fails - refuse, exit 4.
• npm publish 403 - token expired or wrong scope. Print

re-creation command, exit 5.

• Post-publish probe fails - npm caching delay; retry once after 5s,

then warn and exit 0 (the publish itself succeeded).

Rubric

criteria:
  - name: npm_publish_success
    kind: deterministic
    check: "The command 'npm publish --access public' must complete successfully and the package with the new version must be resolvable via 'https://registry.npmjs.org/snappy-os/<new-version>'."
  - name: git_tag_and_push
    kind: deterministic
    check: "A git tag in the format 'v<new-version>' must be created and pushed to the origin repository."
  - name: dependencies_check_passes
    kind: deterministic
    check: "The 'npm run check' command (typecheck + lint + runtime drift check) must exit with a success code."
  - name: contract_stub_check_passes
    kind: deterministic
    check: "The 'npm run contract:stub' command (13 assertions on the eval-endpoint contract) must exit with a success code."

publish-bootstrap - loader

Per-turn rules for the publish-bootstrap skill. Full reference: state/skills/publish-bootstrap/SKILL.md. Do not skip these.

Critical Rules

• NEVER persist NPM_TOKEN to ~/.npmrc. The script writes a temp .npmrc for the publish call only - never bash-fallback the token.
• NEVER publish on a dirty working tree (anything outside package.json). The script refuses with exit 3 - don't override.
• ALWAYS run npm run check (typecheck + lint + drift) AND npm run contract:stub (13 assertions) BEFORE npm publish.
• ALWAYS use a granular access token with bypass-2FA, scoped to snappy-os only. Created at https://www.npmjs.com/settings/robertboulos/tokens.
• ALWAYS git-tag v<new-version> and push the tag after a successful publish.

Commands

| ui dashboard | state/skills/publish-bootstrap/resources/ui.openui | |invoke: bash state/bin/publish-bootstrap.sh (patch bump default) |minor: bash state/bin/publish-bootstrap.sh --bump minor |major: bash state/bin/publish-bootstrap.sh --bump major |dry-run: bash state/bin/publish-bootstrap.sh --dry |verify: curl -s https://registry.npmjs.org/snappy-os/<new-version> | jq .version |eval log: state/log/evals.ndjson (skill: "publish")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/publish-bootstrap/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Exit codes are load-bearing: 2 = no token, 3 = dirty tree, 4 = check failed, 5 = publish 403 (token expired/wrong scope).
• Post-publish probe may 404 briefly due to npm caching - script retries once after 5s, then warns and exits 0 (publish itself succeeded).
• The eval row's primary_issue field is null on success or a short error tag - use it to triage failures from evals.ndjson.

Self-Test

An agent reading this should correctly:

1. [ ] Refuse to publish without NPM_TOKEN in .env.cache
2. [ ] Run npm run check and npm run contract:stub before npm publish
3. [ ] Tag the published version with git tag v<version> and push

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] publish-bootstrap: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] publish-bootstrap: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.