📝 Improve public repository readiness

[nbsp1221]

Summary

• Rework the README into a public-facing landing page with badges, prerequisites, npm installation, a focused quick start, workspace guidance, and links to canonical technical documentation.
• Add repository community-health documentation and templates for contributions, security reports, conduct expectations, bug reports, feature requests, and pull requests.
• Refresh the test documentation to match the current CLI-oriented test surface.

Verification

• pnpm format:check && pnpm lint && pnpm typecheck — passed with no lint warnings or errors.
• vitest run --project unit --project integration — 40 tests across 11 files passed.
• tsdown — production CLI bundle built successfully.
• npm pack plus a temporary global install — the packaged chat2shell --help command ran successfully.
• Documentation checks — local Markdown links resolve and the README renders successfully through GitHub's GFM renderer.

Notes

This change is documentation and repository metadata only; it does not change runtime behavior.

[leverframe]

Leverframe review

⚪ Incremental review completed in 950s

• 1 new finding
• 1 existing finding was verified fixed
• 31 of 31 changed files reviewed
• Verification: 5 passed, 1 failed, 1 not run

Changes a24a700..447f744 · Commit 447f744 · Open review · View check run

[leverframe]

Leverframe review

One low-severity documentation defect found. Review used the repository-pinned pnpm 11.23.0 with Node v24.20.0. The full prescribed quality gate passed, and all changed files were materially inspected.

Findings

1 finding was published inline.

Checks

6 passed · 0 failed · 0 not run

Show 6 checks

Status	Check	Evidence
🟢 passed	git diff --check 3169bd993f8492089316aecf6a2c1e6e39dc21ec...a24a70069534d36a72f65283d7780b068ffc39f6	No whitespace errors.
🟢 passed	pnpm install --frozen-lockfile	Installed 329 packages using repository-pinned pnpm 11.23.0 under Node v24.20.0; lockfile and supply-chain policy verification passed.
🟢 passed	pnpm check	Formatting, oxlint/eslint, TypeScript, 11 unit/integration test files with 40 tests, and the Node 24 production build all passed.
🟢 passed	pnpm dlx yaml --json --single --strict ... | jq ...	Both issue forms and the issue-template configuration parsed as strict YAML and satisfied their required structural constraints.
🟢 passed	Local Markdown target check and curl checks for added external URLs	All local links resolve. The OpenAI tunnel guide, Docker Sandboxes documentation, CI workflow/badge, and badge endpoints responded successfully; the new SECURITY.md link resolves at the reviewed head SHA.
🟢 passed	pnpm pack --dry-run	Produced a valid chat2shell@0.2.0 package manifest containing the built CLI and documented package files.

Limitations

• Docker Sandboxes (sbx) was unavailable, so the real E2E suite was not run. No sandbox/runtime code changed, and repository guidance assigns this documentation-only change to the normal pnpm check boundary.

[leverframe]

Leverframe review

Found one medium-severity state-integrity defect. Verification used the CI-selected Node 24 environment: Node v24.20.0, pnpm 11.23.0, npm 11.19.0, and Docker Engine 29.7.2.

Findings

🟡 [MEDIUM] Capacity rejection permanently cancels workspace retention

src/sandbox/service.ts:118 · confidence: high

When workspace_id refers to a retained managed workspace, getApproved first changes it to approved and clears retained_until. If another sandbox already fills maxActiveSandboxes, this subsequent admission attempt returns false and throws without restoring the workspace. The failed request therefore leaves no sandbox but makes the managed files ineligible for trashExpired, which only processes retained workspaces, defeating the documented 30-day cleanup policy indefinitely.

Evidence: A focused integration test created and destroyed a managed sandbox, filled the one-sandbox limit with another sandbox, and attempted to recreate the retained workspace. After the expected limit error, the assertion that retention was preserved failed: expected {status: "retained", retainedUntil: <timestamp>} but received {status: "approved", retainedUntil: undefined}.

Suggested action: Do not reactivate a retained workspace until sandbox admission succeeds, or restore its previous retained status and deadline when insertSandboxWithinLimit rejects the creation.

Checks

5 passed · 1 failed · 1 not run

Show 7 checks

Status	Check	Evidence
🟢 passed	node --version && pnpm --version && npm --version	Node v24.20.0, pnpm 11.23.0, and npm 11.19.0; pnpm exactly matches package.json and CI.
🟢 passed	pnpm install --frozen-lockfile && pnpm check	Frozen installation passed; formatting, linting, typecheck, 53 unit/integration tests across 13 files, and the Node 24 production build all passed.
🔴 failed	pnpm exec vitest run --project integration test/integration/review-retention-limit.test.ts	The temporary focused regression test reproduced the finding: capacity denial changed the retained workspace to approved and cleared retainedUntil. The temporary test was removed afterward and the worktree was clean.
🟢 passed	npm pack --dry-run --json && node dist/cli.mjs --version	The package includes the executable production bundle and reports chat2shell 0.1.0.
🟢 passed	pnpm release patch --dry-run --ci --verbose	In an isolated clone with an upstream configured, release-it resolved 0.1.1, invoked stable-version validation, and simulated the bump, commit, tag, and push.
🟢 passed	git diff --check a24a70069534d36a72f65283d7780b068ffc39f6...447f744fc42497923fd22016f629fe2369bd963d	No whitespace errors were reported.
⚪ not run	pnpm test:e2e	The repository-required Docker Sandboxes sbx executable is not installed; preflight returned sbx: command not found.

Limitations

• Real microVM verification of the new sbx create --memory path and modified lifecycle E2E test remained unavailable because Docker Sandboxes sbx is absent, although Docker Engine 29.7.2 is available.