Getting Started Pages Repair Design
Goal
Restore the public Getting Started URL and turn the guide into a reliable, security-conscious path from zero setup to a verified connected tab.
Architecture
Keep two regular-file copies of the guide: the Pages-owned copy at docs/getting-started.md and the skill-packaged copy at skills/write-actions-json/references/getting-started.md. A focused Node test requires both to be regular files, byte-identical, internally linkable, and free of the ten confirmed content defects. This deliberately favors robust Pages, archive, npm, and Windows behavior over a cross-tree symlink or a generation-only build artifact.
Ten issues and required corrections
- Replace the broken source-escaping Pages symlink with a regular file.
- Add a focused pre-deploy documentation test that catches Pages-source symlinks and missing rendered inputs.
- Enforce byte-for-byte parity between the Pages and skill copies.
- Add an explicit prerequisites section covering Chrome, Node/npm, a supported MCP client, and OpenAI API access/billing.
- Correct credential hydration: document
ACTIONS_JSON_OPENAI_API_KEYand.actions-json.local.json; do not imply the bridge discovers an arbitrary coding-agent key. - Add extension/bridge version inspection and compatibility guidance, acknowledging that release and npm versions can differ.
- Add SHA-256 verification for the downloaded extension using the release
SHA256SUMS.txt. - Replace abstract verification with concrete bridge health, runtime inventory, and expected-result checks plus a diagnostic order.
- Add a prominent security warning for
0.0.0.0, reachable bridge addresses, firewall/VPN restriction, and the absence of a public-Internet deployment recommendation. - Remove the duplicate bookmarklet headings and visible TODO from the success path; move the unavailable path into a concise limitations section.
Verification
- Focused Node tests begin red against the current symlink and stale content, then pass after the rewrite.
scripts/validate-skills.mjsis run and its pre-existing unrelated canonical-skill-count failure is recorded separately.- The GitHub Pages Jekyll build runs against the repaired worktree and must generate
_site/getting-started.html. - A local HTTP probe of the built site must return 200 for
/getting-started.htmland contain the expected title and verification sections. - After merge/deployment, the public URL must return 200 and the Pages workflow must be green.
Delivery
Commit the investigation, content, tests, and verification evidence on an isolated branch. Open a pull request to yaniv256/actions.json, merge only after checks pass, then verify the production URL independently.