Add issue forms, a light PR template, and an Alpha banner

.agents/manifests/specs.yaml

@@ -1,5 +1,7 @@
 id: specs
 globs:
+  - .github/ISSUE_TEMPLATE/**
+  - .github/pull_request_template.md
   - .github/workflows/**
   - .gitignore
   - CHANGELOG.md
@@ -27,6 +29,8 @@ primary_specs:
 verification_profile: spec-only
 commit_required: true
 allowed_paths:
+  - .github/ISSUE_TEMPLATE/**
+  - .github/pull_request_template.md
   - .github/workflows/**
   - .gitignore
   - CHANGELOG.md

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,74 @@
+name: Bug
+description: Something already documented does not behave as specified.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode** to
+        create or run iOS Simulators. Interfaces can change.
+
+        Use the install-failure form if `simbroker` never became usable.
+        Do not paste credentials, private home paths, customer data, or
+        live lease files.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Which command, app pane, or script misbehaved?
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What should have happened?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `simbroker …`
+        2. …
+        3. See the error
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      description: Tagged Alpha such as 0.1.0-alpha.1, or a short commit SHA.
+      placeholder: 0.1.0-alpha.1
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: macOS, Xcode, and Node.js versions. No private paths.
+      value: |
+        - macOS:
+        - Xcode:
+        - Node.js:
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Redacted logs
+      render: shell
+    validations:
+      required: false
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Before submitting
+      options:
+        - label: I understand this is Alpha, macOS-only, and requires Xcode.
+          required: true
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: I removed credentials, private paths, and customer data from this report.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security advisory
+    url: https://github.com/fiveonecode/simulator-broker/security/advisories/new
+    about: Report a vulnerability privately. Do not open a public issue.
+  - name: Getting started
+    url: https://github.com/fiveonecode/simulator-broker/blob/main/docs/getting-started.md
+    about: Install and first-run help. This project is Alpha, macOS-only, and needs Xcode.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,52 @@
+name: Feature
+description: Propose a change that is not already in the Alpha contract.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode**.
+        It is maintenance-only infrastructure. There is no Homebrew formula,
+        notarized app, or npm package yet.
+
+        Maintainers may decline requests that add a feature, commercialization,
+        or UX roadmap.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you hitting?
+      description: Describe the gap a stranger hits today. Not a solution yet.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What should change?
+      description: A concrete, bounded change. Link docs or specs if you have them.
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Which surface is this about?
+      options:
+        - CLI / broker-core
+        - Local brokerd service
+        - macOS operator app
+        - Install or packaging
+        - Docs or contributor track
+        - Other
+    validations:
+      required: true
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Before submitting
+      options:
+        - label: I understand this is Alpha, macOS-only, and requires Xcode.
+          required: true
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: This is not a security report. I will use a private advisory for vulnerabilities.
+          required: true

.github/ISSUE_TEMPLATE/install-failure.yml

@@ -0,0 +1,82 @@
+name: Install failure
+description: The CLI, tarball, or local installer did not work on this Mac.
+title: "[Install]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode** to
+        create or run iOS Simulators. There is no Homebrew formula, notarized
+        app, or npm package yet.
+
+        Do not paste credentials, private home paths, customer data, or
+        live lease files. Redact logs first. Security reports go through
+        [GitHub Security Advisories](https://github.com/fiveonecode/simulator-broker/security/advisories/new),
+        not a public issue.
+  - type: dropdown
+    id: install-path
+    attributes:
+      label: What install path did you use?
+      options:
+        - CLI-only (`bash scripts/install_local.sh --cli-only`)
+        - Contributor app + CLI (`npm run install:local`)
+        - Alpha CLI tarball from GitHub Releases
+        - Other (describe below)
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command that failed
+      description: Paste the exact command. Do not include private paths.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected-actual
+    attributes:
+      label: Expected versus actual
+      description: What should have happened, and what happened instead?
+    validations:
+      required: true
+  - type: input
+    id: macos
+    attributes:
+      label: macOS version
+      placeholder: "15.6"
+    validations:
+      required: true
+  - type: input
+    id: xcode
+    attributes:
+      label: Xcode version
+      placeholder: "16.4"
+    validations:
+      required: true
+  - type: input
+    id: node
+    attributes:
+      label: Node.js version
+      placeholder: "20.19.0"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Redacted logs
+      description: Paste only the relevant output. Strip home directories and secrets.
+      render: shell
+    validations:
+      required: false
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Before submitting
+      options:
+        - label: I understand this is Alpha, macOS-only, and requires Xcode.
+          required: true
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: I removed credentials, private paths, and customer data from this report.
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## What changed
+
+<!-- A few sentences. Keep the diff focused on one change. -->
+
+## How you verified
+
+A public patch uses Node.js 20 and the Node suites that match the change.
+You do not need the agent harness or a task session directory.
+
+- [ ] `npm run test:broker-core` / `npm run test:client` / `npm run test:harness-adoption` as applicable, or I explained why a deterministic test is not available
+- [ ] I did not commit private paths, credentials, generated Xcode projects, local broker state, or task-session artifacts
+
+## Notes
+
+This project is **Alpha**, **macOS-only**, and needs **Xcode** to talk to iOS
+Simulators. See [CONTRIBUTING.md](CONTRIBUTING.md).

CONTRIBUTING.md

@@ -2,6 +2,11 @@
 
 Thanks for taking the time to improve Simulator Broker.
 
+This project is **Alpha**, **macOS-only**, and needs **Xcode** to create or run
+iOS Simulators. Report install failures, bugs, and feature requests with the
+[issue forms](https://github.com/fiveonecode/simulator-broker/issues/new/choose).
+Look at issues labeled `good first issue` if you want a bounded starter task.
+
 This page has two tracks:
 
 1. **Public patches** — Node.js 20 and the Node test suites. You do not need
@@ -38,6 +43,9 @@ and you do not need to create a task session directory.
 
 ### Pull requests
 
+The pull-request template is a short public-patch checklist. It does not ask
+for a harness session directory.
+
 - Keep changes focused and reviewable.
 - Include tests or explain why a deterministic test is not available.
 - Keep private or local context out of committed files.

README.md

@@ -3,7 +3,10 @@
 A local control plane so humans, AI agents, and CI jobs can share iOS Simulators
 on one Mac without stealing devices from each other.
 
-**Status:** Alpha · macOS only · Xcode required
+> **Alpha.** macOS only. Xcode is required to create or run iOS Simulators.
+> Interfaces can change. There is no Homebrew formula, notarized app, or npm
+> package yet.
+
 [![Node tests](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml/badge.svg)](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml)
 
 Simulator Broker leases simulator aliases by *purpose* (for example
@@ -97,6 +100,7 @@ casually on a machine whose simulator inventory you cannot afford to change.
 - [Getting started](docs/getting-started.md) — install, first-run, reinstall, and uninstall
 - [Concepts](docs/concepts.md) — host, project, purpose, lease, pin, and `brokerd`
 - [Current capabilities](docs/status.md) — what this Alpha already implements
+- [Open an issue](https://github.com/fiveonecode/simulator-broker/issues/new/choose) — install failure, bug, or feature
 - [Harness integration](spec/harness-integration.md) — make a consumer repo broker-aware
 - [Sample consumer repo](examples/harness-adoption/sample-consumer-repo/README.md)
 

docs/getting-started.md

@@ -8,6 +8,10 @@ human-readable text by default; pass `--json` for machine-readable payloads.
 A small public patch follows the public-patches track in
 [CONTRIBUTING.md](../CONTRIBUTING.md); it does not require the agent harness.
 
+> **Alpha.** macOS only. Xcode is required to create or run iOS Simulators.
+> Interfaces can change. There is no Homebrew formula, notarized app, or npm
+> package yet.
+
 ## Prerequisites
 
 - macOS with Xcode and iOS Simulator support installed
@@ -144,6 +148,12 @@ npm run package:distribution
 GitHub Releases attach the Alpha CLI tarball. A signed, notarized app is not
 published there yet.
 
+## Report a problem
+
+Use the GitHub issue forms. Pick **Install failure**, **Bug**, or **Feature**.
+Do not paste credentials, private home paths, or live lease files. Security
+reports go through [SECURITY.md](../SECURITY.md), not a public issue.
+
 ## What to read next
 
 - [Concepts](concepts.md)

docs/status.md

@@ -27,6 +27,8 @@ This Alpha already includes:
 - tagged Alpha CLI tarball through `npm run package:cli` and GitHub Releases
 - public Node test CI on GitHub-hosted Ubuntu for broker-core, client,
   harness-adoption, and public-surface checks
+- GitHub issue forms for install failure, bug, and feature, plus a light PR
+  template that does not require a harness session
 - local-debug packaging through `npm run package:local`
 - signed distribution packaging through `npm run package:distribution`
 - `simbroker project init` for `.simulator-broker/project.json`
@@ -63,4 +65,3 @@ node client/bin/simbroker.mjs simulators boot --alias ui-1
 ## Lower-priority public follow-through
 
 - Homebrew formula, notarized app, and npm package
-- issue templates and starter issues

docs/test/front-door.test.mjs

@@ -37,6 +37,7 @@ test("README first screen is a product front door, not an implementation changel
   assert.ok(screen.includes("Alpha"));
   assert.ok(screen.includes("macOS"));
   assert.ok(screen.includes("Xcode"));
+  assert.ok(screen.includes("> **Alpha.**"), "README first screen must use a visible Alpha banner");
   assert.equal(
     screen.includes("a first extracted file-backed `broker-core` slice exists"),
     false,
@@ -174,6 +175,57 @@ test("release workflow packages the CLI tarball on version tags", () => {
   assert.equal(release.includes("test:app"), false);
 });
 
+test("issue forms cover install failure, bug, and feature and state Alpha limits", () => {
+  const config = readRepoFile(".github/ISSUE_TEMPLATE/config.yml");
+  const install = readRepoFile(".github/ISSUE_TEMPLATE/install-failure.yml");
+  const bug = readRepoFile(".github/ISSUE_TEMPLATE/bug.yml");
+  const feature = readRepoFile(".github/ISSUE_TEMPLATE/feature.yml");
+
+  assert.ok(config.includes("blank_issues_enabled: false"));
+  assert.ok(config.includes("security/advisories"));
+  assert.ok(install.includes("name: Install failure"));
+  assert.ok(bug.includes("name: Bug"));
+  assert.ok(feature.includes("name: Feature"));
+  assert.ok(install.includes("install_local.sh --cli-only"));
+  assert.ok(bug.includes("labels:"));
+  assert.ok(feature.includes("enhancement"));
+  for (const body of [install, bug, feature, config]) {
+    assert.ok(body.includes("Alpha"), "community forms must say Alpha");
+    assert.ok(body.includes("macOS"), "community forms must say macOS");
+    assert.ok(body.includes("Xcode"), "community forms must say Xcode");
+  }
+});
+
+test("PR template is a public-patch checklist and does not require the harness", () => {
+  const template = readRepoFile(".github/pull_request_template.md");
+
+  assert.ok(template.includes("npm run test:broker-core"));
+  assert.ok(template.includes("npm run test:client"));
+  assert.ok(template.includes("npm run test:harness-adoption"));
+  assert.ok(template.includes("Alpha"));
+  assert.ok(template.includes("macOS"));
+  assert.ok(template.includes("Xcode"));
+  assert.equal(template.includes("agent:context"), false);
+  assert.equal(template.includes("agent:verify"), false);
+  assert.equal(template.includes("agent:complete"), false);
+  assert.equal(template.includes("session-dir"), false);
+  assert.equal(template.includes("$HOME/.codex"), false);
+});
+
+test("status and contributing point strangers at issue forms, not later-sequence work", () => {
+  const status = readRepoFile("docs/status.md");
+  const contributing = readRepoFile("CONTRIBUTING.md");
+  const gettingStarted = readRepoFile("docs/getting-started.md");
+  const readme = readRepoFile("README.md");
+
+  assert.ok(status.includes("GitHub issue forms"));
+  assert.equal(status.includes("issue templates and starter issues"), false);
+  assert.ok(contributing.includes("issues/new/choose"));
+  assert.ok(contributing.includes("good first issue"));
+  assert.ok(gettingStarted.includes("Report a problem"));
+  assert.ok(readme.includes("issues/new/choose"));
+});
+
 test("package_cli.sh writes a runnable CLI tarball without tests or the app", () => {
   const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), "simbroker-package-cli-"));
   const result = spawnSync("bash", [path.join(repoRoot, "scripts/package_cli.sh"), "--output-dir", outputDir], {