chore: add vouch system for first-time contributors

.github/CODEOWNERS

@@ -4,3 +4,6 @@
 # Agent infrastructure — tighter review
 .agents/ @NVIDIA/openshell-codeowners
 AGENTS.md @NVIDIA/openshell-codeowners
+
+# Vouch list — maintainers only (bot commits bypass, but manual edits need review)
+.github/VOUCHED.td @NVIDIA/openshell-codeowners

.github/DISCUSSION_TEMPLATE/vouch-request.yml

@@ -0,0 +1,45 @@
+title: "Vouch request: [your GitHub username]"
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Vouch Request
+
+        OpenShell uses a vouch system for first-time contributors. Fill out this
+        form to request approval. A maintainer will review and comment `/vouch`
+        if approved.
+
+        **Write in your own words.** Do not have an AI generate this request.
+        Requests that read like LLM output will be denied.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What do you want to work on?
+      description: >
+        Describe the change you want to make. Link to an existing issue if
+        there is one.
+      placeholder: "I want to fix #123 which causes sandbox timeouts when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why this change?
+      description: >
+        Explain your motivation and why this matters. Keep it concise.
+      placeholder: "This bug affects anyone running sandboxes on ARM64 because..."
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I wrote this request myself (not AI-generated)
+          required: true
+        - label: I have read [CONTRIBUTING.md](https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md)
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,11 @@
 blank_issues_enabled: false
 contact_links:
+  - name: First-time contributor? Get vouched first
+    url: https://github.com/NVIDIA/OpenShell/discussions/new?category=vouch-request
+    about: >
+      First-time contributors must be vouched before submitting PRs. Open a
+      Vouch Request discussion describing what you want to work on. A
+      maintainer will approve you with /vouch.
   - name: Have a question?
     url: https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md#agent-skills-for-contributors
     about: >

.github/VOUCHED.td

@@ -0,0 +1,10 @@
+# Vouched Contributors
+#
+# Users listed here have been approved to submit pull requests.
+# Org members and collaborators with write access bypass this check automatically.
+#
+# Maintainers vouch new contributors by commenting "/vouch" on their
+# Vouch Request discussion. The vouch-command workflow updates this file.
+#
+# Format: one GitHub username per line, no @ prefix. Sorted alphabetically.
+# Prefix with - to denounce. See https://github.com/mitchellh/vouch for details.

.github/workflows/vouch-check.yml

@@ -0,0 +1,21 @@
+name: Vouch Check
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  vouch-gate:
+    if: github.repository_owner == 'NVIDIA'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: mitchellh/vouch/action/check-pr@v1
+        with:
+          pr-number: ${{ github.event.pull_request.number }}
+          auto-close: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/vouch-command.yml

@@ -0,0 +1,30 @@
+name: Vouch Command
+
+on:
+  discussion_comment:
+    types: [created]
+
+concurrency:
+  group: vouch-manage
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  discussions: write
+
+jobs:
+  process-vouch:
+    if: github.repository_owner == 'NVIDIA'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: mitchellh/vouch/action/manage-by-discussion@v1
+        with:
+          discussion-number: ${{ github.event.discussion.number }}
+          comment-node-id: ${{ github.event.comment.node_id }}
+          vouch-keyword: "/vouch"
+          denounce-keyword: "/denounce"
+          unvouch-keyword: "/unvouch"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -45,11 +45,19 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
 | `.agents/agents/` | Agent personas | Sub-agent definitions (e.g., reviewer, doc writer) |
 | `architecture/` | Architecture docs | Design decisions and component documentation |
 
+## Vouch System
+
+- First-time external contributors must be vouched before their PRs are accepted. The `vouch-check` workflow auto-closes PRs from unvouched users.
+- Org members and collaborators bypass the vouch gate automatically.
+- Maintainers vouch users by commenting `/vouch` on a Vouch Request discussion. The `vouch-command` workflow appends the username to `.github/VOUCHED.td`.
+- Skills that create PRs (`create-github-pr`, `build-from-issue`) should note this requirement when operating on behalf of external contributors.
+
 ## Issue and PR Conventions
 
 - **Bug reports** must include an agent diagnostic section — proof that the reporter's agent investigated the issue before filing. See the issue template.
 - **Feature requests** must include a design proposal, not just a "please build this" request. See the issue template.
 - **PRs** must follow the PR template structure: Summary, Related Issue, Changes, Testing, Checklist.
+- **PRs from unvouched external contributors** are automatically closed. See the Vouch System section above.
 - **Security vulnerabilities** must NOT be filed as GitHub issues. Follow [SECURITY.md](SECURITY.md).
 - Skills that create issues or PRs (`create-github-issue`, `create-github-pr`, `build-from-issue`) should produce output conforming to these templates.
 

CONTRIBUTING.md

@@ -2,6 +2,40 @@
 
 OpenShell is built agent-first. We design systems and use agents to implement them. Your agent is your first collaborator — point it at this repo before opening issues, asking questions, or submitting code.
 
+## The Critical Rule
+
+**You must understand your code.** Using AI agents to write code is not just acceptable, it's how this project works. But you must be able to explain what your changes do and how they interact with the rest of the system. If you can't, don't submit it.
+
+Submitting agent-generated code without understanding it — regardless of how clean it looks — wastes maintainer time and will result in your PR being closed. Repeat offenders will be blocked from the project.
+
+## AI Usage
+
+OpenShell is agent-first, not agent-only. The distinction matters:
+
+- **Do** use agents to explore the codebase, run diagnostics, generate code, and iterate on implementations.
+- **Do** use the skills in `.agents/skills/` — they exist to make your agent effective.
+- **Do** interrogate your agent until you understand every edge case and interaction in your changes.
+- **Don't** submit code you can't explain without your agent open.
+- **Don't** use agents as a substitute for understanding the system. Read the architecture docs.
+
+## First-Time Contributors
+
+We use a vouch system. This exists because AI makes it trivial to generate plausible-looking but low-quality contributions, and we can no longer trust by default.
+
+1. Open a [Vouch Request](https://github.com/NVIDIA/OpenShell/discussions/new?category=vouch-request) discussion.
+2. Describe what you want to change and why.
+3. Write in your own words. AI-generated vouch requests will be denied.
+4. A maintainer will comment `/vouch` if approved.
+5. Once vouched, you can submit pull requests.
+
+**If you are not vouched, any pull request you open will be automatically closed.** Org members and collaborators with push access bypass this check.
+
+### Finding Work
+
+Issues labeled [`good-first-issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) are scoped, well-documented, and friendly to new contributors. Start there. If you need guidance, comment on the issue.
+
+All open issues are actionable — if it's in the issue tracker, it's ready to be worked on.
+
 ## Before You Open an Issue
 
 This project ships with [agent skills](#agent-skills-for-contributors) that can diagnose problems, explore the codebase, generate policies, and walk you through common workflows. Before filing an issue: