secondly-com · adamcohenhillel · Jul 6, 2026 · Jul 6, 2026 · chatgpt-codex-connector · Jul 6, 2026
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -121,6 +121,29 @@ By contributing, you represent and warrant that:
   rate limits, data minimization, or licensing controls without explicit
   approval.
 
+## CI Ladder
+
+CI runs in three tiers. Only the first tier runs automatically on fork PRs;
+the heavier tiers need maintainer involvement.
+
+1. **Automatic on every PR** (`ci.yml`, ~10 minutes): docs-site build,
+   `./scripts/check.sh` (required files, JSON validity, schema
+   cross-consistency, runtime protocol validation, broker smoke test, Node
+   contract tests, assistant Java compile check), and `git diff --check`.
+   Run `./scripts/check.sh` locally before pushing — it is the same check.
+2. **Maintainer-triggered** (`gcp-lab.yml`): a maintainer applies the
+   `run-gcp-lab` label to run the GCP emulator smoke lab (~30–60 minutes).
+   Ask for a lab run in a PR comment when your change affects the image,
+   overlay, patches, or on-device behavior.
+3. **Release and nightly only**: `emulator.yml` (self-hosted arm64 emulator
+   smoke) and `eval.yml` (nightly on-device trajectory smokes and benchmark).
+   These do not run on fork PRs.
+
+Reviews are best-effort. If tier 1 is green and you need a lab run or a
+review, comment on the PR.
+
+The milestone tracks and current priorities are in [ROADMAP.md](../ROADMAP.md).
+
 ## Questions
 
 For licensing, commercial use, or contribution questions, contact support@secondly.com.

diff --git a/README.md b/README.md
@@ -172,6 +172,12 @@ See [docs/devices/MATRIX.md](docs/devices/MATRIX.md) and
 Contributions, issues, and device validation reports are welcome under the
 terms in [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
 
+- [ROADMAP.md](ROADMAP.md) — milestone tracks and current priorities.
+- [Discussions](https://github.com/secondly-com/OpenPhone/discussions) — for
+  questions, ideas, and show-and-tell; use issues for bugs and concrete work.
+- [No-build contribution path](docs/contributing/no-build.md) — schemas,
+  broker, integrations, protocol, and docs work needs no Android build host.
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=secondly-com/OpenPhone&type=Date)](https://www.star-history.com/#secondly-com/OpenPhone&Date)

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -0,0 +1,45 @@
+# OpenPhone Roadmap
+
+Work is organized into five milestone tracks. Each links to a GitHub
+milestone with the full issue list. If you want to contribute, pick an issue
+from a track that matches your interests — `good first issue` labels mark
+entry-level work, and the [no-build contribution
+path](docs/contributing/no-build.md) covers what you can do without an
+Android build host.
+
+Tracking issue: [#97](https://github.com/secondly-com/OpenPhone/issues/97).
+
+## [M1: Safety & Policy Hardening](https://github.com/secondly-com/OpenPhone/milestone/1)
+
+Fix policy-bypass and confirmation gaps across the assistant, watchers, and
+the ADB/MCP surface. In progress — capability inference now fails closed and
+the external ADB/MCP transport refuses state-changing tools by default.
+Must land before wider distribution.
+
+## [M2: Testability & Decomposition](https://github.com/secondly-com/OpenPhone/milestone/2)
+
+Break up the assistant god classes, add a JUnit harness, and cover
+pure-logic classes with tests. Started — thread-safety fixes are under
+review; decomposition has not begun.
+
+## [M3: Upstream Durability](https://github.com/secondly-com/OpenPhone/milestone/3)
+
+Fork `frameworks_base`, add patch-apply canary CI against LineageOS
+upstream, and write a LineageOS-bump runbook so upstream bumps stop being
+high-risk events. Not started; post-0.1.
+
+## [M4: Provider & Runtime Maturity](https://github.com/secondly-com/OpenPhone/milestone/4)
+
+Broker streaming, rate limiting, and provider dispatch; MCP spec
+compliance; runtime protocol versioning; a shared runtime-protocol package.
+In progress — MCP stdio framing and broker rate-limiter fixes have landed.
+
+## [M5: Contributor Experience & Community](https://github.com/secondly-com/OpenPhone/milestone/5)
+
+Prebuilt emulator images, a documented no-build contribution path, and
+community infrastructure (Discussions, roadmap, contribution docs). In
+progress.
+
+---
+
+Updated quarterly. Horizons are directional, not commitments.
diff --git a/docs/BUILD.md b/docs/BUILD.md
@@ -3,6 +3,12 @@
 OpenPhone uses Android's normal `repo` workflow. This repository stays small
 and contains only OpenPhone-owned code, manifests, scripts, and patches.
 
+> **Minimum build-host specs: 64 GB RAM, ~700 GB fast disk, x86_64 Linux.**
+> A full Android build will not complete on a typical laptop. If your machine
+> does not meet the bar, you can still contribute meaningfully without an
+> Android build host — see the
+> [no-build contribution path](contributing/no-build.md).
+
 ## Prerequisites
 
 - Linux Android build host dependencies installed for full device images.

diff --git a/docs/contributing/meta.json b/docs/contributing/meta.json
@@ -0,0 +1,6 @@
+{
+  "title": "Contributing",
+  "pages": [
+    "no-build"
+  ]
+}
diff --git a/docs/contributing/no-build.md b/docs/contributing/no-build.md
@@ -0,0 +1,92 @@
+# Contributing Without an Android Build Host
+
+A full OpenPhone Android build needs 64 GB RAM, ~700 GB fast disk, and an
+x86_64 Linux host. Most of the repository does not. Everything below is
+plain JSON, JavaScript, Python, shell, and markdown, validated end-to-end by
+`./scripts/check.sh` on an ordinary laptop.
+
+## What you can work on
+
+- [`schemas/`](https://github.com/secondly-com/OpenPhone/tree/main/schemas)
+  — JSON Schema contracts for action requests, tools, screen context, audit
+  events, trajectories, OTA feeds, and eval reports. `check.sh` loads
+  several of them for cross-consistency checks.
+- [`runtime/protocol/`](https://github.com/secondly-com/OpenPhone/tree/main/runtime/protocol)
+  — the Runtime Agent Protocol manifests (commands, events, capabilities)
+  and their validator.
+- [`integrations/cli`](https://github.com/secondly-com/OpenPhone/tree/main/integrations/cli),
+  [`integrations/mcp-server`](https://github.com/secondly-com/OpenPhone/tree/main/integrations/mcp-server),
+  [`integrations/adb`](https://github.com/secondly-com/OpenPhone/tree/main/integrations/adb)
+  — Node CLI, MCP server, and ADB transport. Pure `.mjs`, no build step.
+- [`services/model-broker/`](https://github.com/secondly-com/OpenPhone/tree/main/services/model-broker)
+  — the dependency-free Python model broker and its deploy files.
+- [`tests/integrations/`](https://github.com/secondly-com/OpenPhone/tree/main/tests/integrations)
+  — Node contract tests for the CLI, MCP server, and OpenClaw plugin policy
+  buckets.
+- `docs/` — everything on the docs site.
+- [`scripts/`](https://github.com/secondly-com/OpenPhone/tree/main/scripts)
+  — sync, validation, and release helpers.
+
+## Setup
+
+```bash
+git clone https://github.com/secondly-com/OpenPhone.git
+cd OpenPhone
+node --version     # CI uses Node 24
+python3 --version  # any recent Python 3
+./scripts/check.sh
+git diff --check
+```
+
+`check.sh` skips the standalone Java compile check when no Android SDK is
+present (or set `OPENPHONE_SKIP_JAVA_CHECK=1`). Everything else — required
+files, JSON validity, schema cross-consistency, protocol validation, broker
+smoke test, and the Node contract tests — runs locally in a few minutes.
+
+To build the docs site locally, run `./scripts/build-docs.sh` (needs `npm`).
+
+## Example tasks
+
+### Add a schema field
+
+Contracts live in `schemas/*.schema.json`. To document a new payload field,
+edit the schema (for example a new optional property in
+`screen-context.schema.json`), keep `required` accurate, and run
+`./scripts/check.sh`. Note which schemas drive validator behavior directly —
+read
+[schemas/README.md](https://github.com/secondly-com/OpenPhone/blob/main/schemas/README.md)
+before changing enums, `required` keys, or `const` markers.
+
+### Add or change a runtime command
+
+Runtime commands are declared in
+`runtime/protocol/openphone-commands.json`. Each entry needs a name,
+`android_tool`, capability, risk, exposure, and input/output schemas.
+`runtime/protocol/validate-runtime-protocol.mjs` (run by `check.sh`)
+cross-checks the manifest against the Android action registry, the OpenClaw
+plugin command buckets, and the Android adapter mapping — so a new command
+also touches those files, but all of them are text edits validated without
+a build. Start by reading an existing entry like `openphone.apps.search`.
+
+### Fix or improve docs
+
+Edit the markdown under `docs/`, keep relative links valid, and run
+`./scripts/check.sh` plus `./scripts/build-docs.sh` if you can. New pages
+need an entry in the directory's `meta.json` to appear in the docs-site nav.
+
+### Extend a broker or integration test
+
+The broker's behavior contract is exercised by
+`scripts/smoke-test-model-broker.sh` (started against a fake provider, no
+API key needed). The Node surfaces are covered by
+`tests/integrations/*.mjs`, which run the CLI and MCP server in dry-run mode
+with no device attached. Adding an assertion for an uncovered behavior is a
+small, high-value PR.
+
+## Before opening a PR
+
+Read the contributor terms in
+[.github/CONTRIBUTING.md](https://github.com/secondly-com/OpenPhone/blob/main/.github/CONTRIBUTING.md),
+keep the PR focused, and make sure `./scripts/check.sh` and
+`git diff --check` pass. The CI ladder that runs on fork PRs is documented
+there too.
diff --git a/docs/meta.json b/docs/meta.json
@@ -19,6 +19,7 @@
     "GMS",
     "---Contribute---",
     "contribution-guide",
+    "contributing",
     "AI_FIRST_ENGINEERING",
     "TESTING",
     "RELEASE_PROCESS",

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -8,6 +8,12 @@ If you just want to read about the system, jump to
 [Architecture](/docs/ARCHITECTURE). If you want to flash an actual Pixel 9a,
 see [Build](/docs/BUILD).
 
+> **Minimum build-host specs: 64 GB RAM, ~700 GB fast disk, x86_64 Linux.**
+> The build host is the machine that produces the image, not the one that
+> runs the emulator. If no machine you have meets the bar, see the
+> [no-build contribution path](/docs/contributing/no-build) — schemas,
+> broker, integrations, protocol, and docs work needs no Android build.
+
 ## What you get
 
 After this quickstart you will have: