docs: clarify native-shell positioning and contributor onboarding

[gtwatts]

Problem and resulting behavior

The repository front door led with control-plane jargon and a broad function inventory, while contributor templates assumed function additions and implied sandboxing. This change leads with a concrete promise: help coding agents work more safely and reliably in native shells. It distinguishes today's reviewed toolkit and exact integration limits from the long-range go-to control-plane ambition.

• Clarify README positioning, Bash-engine versus zsh-caller support, candidate status, and separate reviewed invocation/native hook routes.
• Add a first-session guide and readiness checklist, plus a sequenced open-source growth plan with bounded work packages, ownership, acceptance criteria, pilot metrics, distribution prerequisites, and metadata rollback values. The existing control-plane roadmap remains the engineering authority.
• Make contribution and issue/PR templates useful for setup friction, false blocks, recovery, adapters, and documentation; correct stale links/counts and export guidance.

Public metadata already applied

With explicit owner authorization, updated only the repository About description and topics. Exact API readback matched the intended copy and 17-topic set. Homepage remains the repository URL; public visibility, main default branch, Issues, and Discussions were read back unchanged. The before/after description and topics are recorded in docs/OPEN_SOURCE_GROWTH_PLAN.md for reversal. No access, branch/security settings, license, release rules, billing, secrets, or automation changed.

Validation

• git diff --check: passed.
• Checked 143 local Markdown file/anchor links: passed.
• Parsed all three changed issue YAML files; checked unique form IDs, supported field types, and existing repository labels: passed.
• New onboarding docs copied byte-for-byte from the completed onboarding workstream; their shell snippets parse in Bash and zsh.
• Onboarding owner ran the exact temporary structured-invocation/project-memory recipe in native Bash 5.3.15 and zsh 5.9 on macOS arm64. Existing native setup --proof passed. Linux and live host enforcement remain unverified; restricted-task PermissionError was not treated as a product regression.
• scripts/verify-public-claims.sh with all three new docs included: generated registry and gate parity pass; full check FAILS on canonical SHA256SUMS payload drift at README.md. The README/docs are release payload members, so the final combined candidate requires the release owner's manifest/receipt refresh and matching evidence. This PR deliberately does not modify generated integrity files or weaken gates. Baseline CI also had an expired receipt; no green platform matrix or shipped-fix claim is made.

Review and recovery

Documentation/templates only; no runtime, installer, activation, workflow, or security implementation changes. Revert this commit for content rollback; restore the recorded before-values for metadata rollback. This is a draft pending review and release-integrity integration. No merge or release, pilot invitation, external social post, or paid study is authorized by the plan.

---

Summary by cubic

Reframes MAINFRAME's public positioning from a control-plane promise to a concrete native-shell toolkit, and reworks contributor templates and onboarding docs to match.

New features

• Adds docs/AGENT_ONBOARDING.md, docs/AGENT_READINESS_CHECKLIST.md, and docs/OPEN_SOURCE_GROWTH_PLAN.md with tested first-session recipes, per-cell evidence matrices, bounded work packages, and pilot metrics.
• Issue/PR templates and CONTRIBUTING.md now require exact commit/version, calling shell vs Bash runtime, environment restrictions, expected vs actual results, and recovery impact.
• README distinguishes reviewed invocation routes from native hook coverage, clarifies Bash-engine vs zsh-caller support, and marks the project as an unpublished candidate.
• Updated the repository About description and topics; before/after values are recorded in the growth plan for rollback.

^{Written for commit 1ad0fd6. Summary will update on new commits.}

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}