diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 130d72b1..18a27bf4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,10 +1,14 @@
# Contributing to epac
-Thanks for your interest in helping improve epac. We welcome clear bug reports, thoughtful suggestions, and well-scoped pull requests.
+Thanks for your interest in helping improve epac. This repository is open source so you can inspect how the product works and use your own coding agent to help shape feature proposals.
+
+epac's community contribution path is product-first. We are not currently using community source-code pull requests as the main way to add product features. Instead, we want each substantial contribution to become a well-formed spec that maintainers can review and, if accepted, route into the [Riddim Software](https://riddimsoftware.com/) Factory.
+
+The public intake service and tracker are not live yet. Until they are, use this guide to prepare a proposal before opening a GitHub issue or contacting the maintainers.
## How to report an issue
-Before opening a pull request, start by filing an issue with:
+For a bug report, open an issue with:
- a short, descriptive title
- what you expected to happen
@@ -25,27 +29,70 @@ Attach the validated `SPEC.md` contents or rendered issue body to the issue.
If this is a question or clarification request, reach out via email at [sunny@riddimsoftware.com](mailto:sunny@riddimsoftware.com).
-## How to propose a change
+## How to propose a feature
+
+Start by cloning the repo and opening it in your preferred coding agent. Ask the agent to read this file, `README.md`, `CLAUDE.md` or `AGENTS.md`, and the relevant product or architecture docs before drafting a proposal.
+
+Your agent may edit the checkout locally to explore an idea or draft evidence for the spec. Those edits are scratch work. They are not the expected contribution artifact, and you do not need to run the app locally to contribute.
+
+The expected artifact is one top-level spec. Depending on scope, that spec may describe:
+
+- one issue for a narrow feature or bug fix
+- one project with several child issues
+- one initiative with multiple projects
+
+Do not split one discussion into unrelated proposals. If your idea contains several independent outcomes, ask your agent to identify the single top-level shape or recommend splitting the discussion.
+
+## Factory readiness checklist
+
+A proposal is ready for maintainer review when it includes:
+
+- **Use case** — who the feature is for, what they are trying to do, and what success looks like.
+- **User value** — why this matters for epac users now.
+- **Official data source** — the government or open-data source, owner, URL, format, update cadence, and required fields.
+- **Data provenance** — how any app-visible claim traces back to the source.
+- **App behavior** — what the user will see, do, receive, or configure in epac.
+- **Acceptance criteria** — testable criteria, preferably written as `Given / When / Then`.
+- **Out of scope** — related work that is intentionally not included.
+- **Implementation surface** — likely affected areas such as `ios/`, `backend/`, `website/`, `data/`, `shared/`, or release metadata.
+- **Verification plan** — commands, manual checks, screenshots, or a clear reason verification was not run.
+- **Risks and edge cases** — privacy, stale data, missing data, civic neutrality, App Store review, or release concerns.
+
+If the official data source is unclear, submit a source-discovery proposal instead of a product feature. A good source-discovery proposal explains the user need, candidate sources, and what must be proven before the feature can be built.
+
+## Data source policy
+
+epac is a civic app. Product features must be grounded in authoritative public sources.
+
+- Prefer official government or open-data sources.
+- Do not propose new Riddim-owned runtime backend dependencies for the app.
+- Do not invent, summarize, or rewrite civic facts with generated text.
+- Treat postal code, location, and notification data as sensitive. Explain why the data is needed and how the app can minimize retention or avoid server-side collection.
+- If data is unavailable, stale, licensed restrictively, or not machine-readable, state that clearly in the proposal.
+
+Examples of appropriate source categories include House of Commons open data, Elections Canada electoral geography, Statistics Canada public datasets, and other official Canadian public records.
+
+## What about local edits?
+
+Local edits are optional scratch work. They can help your agent answer questions like:
+
+- Is this feasible in the current architecture?
+- Which module would be affected?
+- What source data shape does the app need?
-1. Open an issue to discuss the change (especially for behavior changes or new features).
-2. Link related issues and docs.
-3. Keep the change focused and include rationale plus trade-offs.
-4. Ask for feedback if you are unsure of scope.
+Please do not open product-feature PRs with those local edits unless a maintainer explicitly asks for one. Maintainers own final implementation, review, release, and App Store submission.
-## Branching and pull requests
+## Pull requests
-- Create a branch from `main`.
-- Keep PRs small and scoped to one purpose.
-- Include a clear title and summary of what changed and why.
-- PRs may receive automated first-pass review; humans review and merge.
-- Reference the issue(s) you are addressing and include test evidence in the PR description.
+Small non-product fixes may still be appropriate as pull requests, such as documentation corrections, typo fixes, broken links, or test-only reproductions requested by a maintainer.
-## Local development expectations
+For any PR a maintainer asks you to open:
-- iOS work: Xcode and the project toolchain required by `ios/README.md`/`README.md`.
-- Backend work: Ruby/Go/Python tooling for your service plus any repository-specific dependencies (for example, `go test`, `swiftlint --strict`, or database/local pipeline prerequisites).
-- Add/update tests where practical and run the relevant checks before opening a PR.
-- Keep file and API changes small and easy to review.
+- create a branch from `main`
+- keep the PR small and scoped to one purpose
+- include a clear title and summary of what changed and why
+- reference the issue or proposal you are addressing
+- include test evidence in the PR description
## Community behavior
diff --git a/README.md b/README.md
index 4cc8f86a..c64c978e 100644
--- a/README.md
+++ b/README.md
@@ -1,128 +1,52 @@
# epac
-**Canada's Parliament, in your pocket — an iPhone app for tracking MPs, bills, votes, debates, expenses, and lobbying activity from official Canadian government sources.**
+epac is built through agent-assisted specs.
-
-
- 
-
-
+The canonical way to contribute is not to set up the app locally, pick a programming language, or send a feature patch. Clone the repo, open it in your coding agent, and use the repository context to turn an idea into a `SPEC.md`.
-
-
- 
-
-
+The spec is the contribution. The [Riddim Software](https://riddimsoftware.com/) Factory takes over from there: it reviews accepted specs, turns them into implementation work, produces something testable, iterates when needed, and can ship the result to TestFlight and the App Store.
-
- Homepage
- ·
- App Store
-
+## How It Works
-## What it does and why
+1. Clone this repository.
+2. Open the repo in your preferred coding agent.
+3. Discuss the feature, bug, or release improvement with the agent.
+4. Let the agent read the repo context and shape the proposal.
+5. Open a spec-only pull request that adds:
-`epac` turns the House of Commons record into something more readable than a feed of PDFs, XML, and committee pages. The app lets Canadians follow what MPs actually do between elections: how they vote, what bills they sponsor, what gets said in debate, and which topics are active in Parliament.
-
-One of its core ideas is **Hansard as chat**. Instead of treating parliamentary debate as a wall of transcript text, epac presents speeches in a conversational format that is faster to scan on a phone while still staying grounded in the official record. The goal is not commentary or partisanship; it is a civic tool that makes primary-source parliamentary data easier to browse, search, and verify.
-
-## Architecture
-
-This repository is intentionally polyglot because each part of the product does a different job:
-
-- **SwiftUI + SwiftData (`ios/`)** — the iPhone app, widgets, app clip, local persistence, and product UI.
-- **Go services (`backend/`)** — API endpoints, ingestion workers, and backend jobs that fetch, normalize, and serve parliamentary data.
-- **Python tools (`backend/` and `scripts/`)** — focused ingestion utilities, release helpers, localization checks, and marketing tooling.
-- **HTML/CSS/JS (`website/`)** — the public website, landing pages, topic pages, and App Store support web surfaces.
-- **Data snapshots (`data/` and bundled app assets)** — source-derived files that help feed the app experience.
-
-Together, those layers support the same product loop: gather authoritative public data, structure it, and deliver it in a mobile experience that makes Parliament easier to follow.
-
-## Build and run
-
-### iOS app
-
-Requirements:
-
-- Xcode with iOS 17+ simulator support
-- macOS
-
-Open the project in Xcode:
-
-```bash
-open ios/epac.xcodeproj
-```
-
-Then select the `epac` scheme and run it in the simulator.
-
-Alternatively, build from the command line using the provided `ios/Makefile`. This path is recommended for first-time contributors as it automatically finds an available simulator.
-
-First, install [xcbeautify](https://github.com/cpisciotta/xcbeautify):
-
-```bash
-brew install xcbeautify
+```text
+proposals//SPEC.md
```
-Then build and run:
+The PR should not include product-code changes unless a maintainer explicitly asks for them. Local edits are fine as scratch work while your agent explores the idea, but they are evidence for the spec, not the artifact we review.
-```bash
-cd ios
-make build # Build the app
-make simulator # Build and deploy to an available simulator
-```
-
-`make simulator` automatically targets an available iPhone simulator. To target a specific one, you can override `SIM_NAME`:
-
-```bash
-cd ios && make simulator SIM_NAME='iPhone 16'
-```
-
-If you prefer to use `xcodebuild` directly, you can list available simulators with `xcrun simctl list devices available` and then specify one:
-
-```bash
-cd ios
-xcodebuild -project epac.xcodeproj -scheme epac -destination 'platform=iOS Simulator,name=YOUR_SIMULATOR_NAME' build
-```
-
-### Backend and tooling prerequisites
+## What Goes In The Spec
-Requirements:
+A useful `SPEC.md` is a short design document. It should explain:
-- Go 1.24+
-- Python 3
+- the problem
+- the goals and non-goals
+- the user jobs or use cases
+- the official government or open-data sources involved
+- how app-visible claims trace back to those sources
+- the proposed product behavior
+- privacy, safety, and civic-neutrality risks
+- validation evidence from the discussion or local exploration
+- open questions and alternatives considered
+- whether the work looks like one issue, a project, or an initiative
-Install the repo's Python dev dependency:
+The most important epac rule: product behavior must be grounded in authoritative public sources. If the data source is unclear, write a source-discovery spec instead of a feature spec.
-```bash
-pip install -r requirements-dev.txt
-```
-
-Useful local checks:
-
-```bash
-cd backend/search && go test ./...
-cd backend/hansard-backfill && go test ./...
-python3 backend/cabinet/cabinet_ingest.py --dry-run
-```
+## What Happens Next
-The iOS app is the main product surface; the backend services and scripts exist to ingest, shape, and publish the public parliamentary data that the app depends on.
+Maintainers review the spec PR. If the spec needs more detail, the reviewer asks for changes and you can continue the discussion with your coding agent. If the spec is accepted, it can be routed into the Riddim Software Factory.
-## Contribute
-
-Issues and pull requests are welcome. Start with [CONTRIBUTING](CONTRIBUTING.md), then read the [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).
-
-Bug fixes can be prepared with the repo-local intake harness:
-
-```bash
-python3 scripts/intake/bugfix_spec.py new
-```
+The factory does a strong job of implementation, but software still needs feedback. Some specs produce a testable result on the first pass. Some need an iteration after testing. The contribution loop is designed for that: spec, implement, test, refine, release.
-This creates a validated `SPEC.md` that captures the observed behavior, expected
-behavior, evidence plan, and reporter validation path before implementation
-starts. See [docs/factory/bugfix-intake.md](docs/factory/bugfix-intake.md).
+Future intake service work may add a tracker that follows an accepted spec into Linear, implementation, PR review, TestFlight, and App Store release. For now, the spec PR is the source of truth.
-PRs may receive an automated first-pass review; humans review and merge.
+## Repo Context
-## License
+This repo contains the source, data tooling, release scripts, and agent-readable project context that a coding agent needs to reason about epac. You do not need to run the app locally to contribute a spec.
-Distributed under the [MIT License](LICENSE).
+For the current contribution rules, read [CONTRIBUTING.md](CONTRIBUTING.md).