diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..9f334e1
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    name: Rust
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        run: |
+          rustup toolchain install stable --profile minimal --component rustfmt,clippy
+          rustup default stable
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Run clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Run tests
+        run: cargo test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..754a6b8
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,51 @@
+# Contributing
+
+Thanks for taking the time to improve `iii-code`.
+
+`iii-code` is intentionally a thin Rust CLI over the installed `iii` binary and
+the public worker stack. Contributions should preserve that boundary: prefer
+terminal UX, payload construction, diagnostics, and documentation changes over
+embedding another agent runtime in this repository.
+
+## Development Setup
+
+Install the Rust stable toolchain, then check the project locally:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+```
+
+The default test suite does not require a running `iii` engine. The ignored
+smoke test exercises the real engine and worker stack:
+
+```bash
+cp config.example.yaml config.yaml
+iii worker add harness
+iii
+cargo test -- --ignored
+```
+
+Run `iii` from the repository root so the example shell filesystem settings are
+jailed to the same directory as the checkout.
+
+## Pull Requests
+
+Keep pull requests focused and include:
+
+- the user-facing behavior or documentation change
+- the commands you ran, including skipped checks if any
+- any required `iii` engine, worker, or provider credential assumptions
+
+Good first changes include:
+
+- README and troubleshooting improvements
+- CLI formatting and diagnostics
+- tests for argument parsing, payload construction, event rendering, and error
+  redaction
+- small terminal UX improvements listed in
+  [docs/feature-parity-gaps.md](docs/feature-parity-gaps.md)
+
+Before opening a larger feature, start with an issue or discussion so the
+worker boundary and public `iii` contracts are clear.
diff --git a/README.md b/README.md
index f8a2387..6b34743 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,32 @@ The boundary is the public `iii` CLI and worker functions:
 cargo install --path .
 ```
 
+## Quickstart
+
+Use this path when you want to try the CLI against a local `iii` engine:
+
+```bash
+git clone https://github.com/rohitg00/iii-code
+cd iii-code
+cp config.example.yaml config.yaml
+export ANTHROPIC_API_KEY=...
+export OPENAI_API_KEY=...
+iii worker add harness
+iii
+```
+
+Then, in another terminal from the same repository:
+
+```bash
+cargo run -- setup
+cargo run -- doctor
+cargo run -- chat "inspect this repo and suggest the first cleanup"
+```
+
+At least one supported provider credential is required. Start `iii` from the
+repository root so the example shell filesystem configuration points at the
+same checkout.
+
 ## Prerequisites
 
 - latest `iii` CLI on `PATH`
@@ -275,6 +301,24 @@ iii-code doctor
 iii-code models
 ```
 
+## Troubleshooting
+
+If `iii worker list` shows workers as `stopped`, confirm the `iii` engine is
+still running in another terminal. The list should change to `running` while
+the engine process is active.
+
+If `shell::fs::ls` reports `S215 path escapes host_root`, stop `iii`, restart
+it from the `iii-code` repository root, and rerun `iii-code doctor`. The sample
+configuration uses `.` for both `shell.fs.host_root` and `shell.working_dir`.
+
+If setup reports a harness SHA256 failure, keep reading the output. The CLI
+falls back to installing the core worker stack individually so local testing can
+continue while the upstream harness artifact is fixed.
+
+If `doctor` reports missing provider auth, export `OPENAI_API_KEY` or
+`ANTHROPIC_API_KEY` and rerun `iii-code setup`. One provider is enough for
+single-provider use.
+
 ## Development
 
 Fresh upstream references were cloned from:
@@ -288,10 +332,14 @@ checkout paths.
 Feature parity notes live in [docs/feature-parity-gaps.md](docs/feature-parity-gaps.md).
 
 ```bash
+cargo fmt --all -- --check
+cargo clippy --all-targets -- -D warnings
 cargo test
-cargo clippy -- -D warnings
 cargo test -- --ignored
 ```
 
 Ignored tests require a running iii engine, installed workers, and provider
 credentials.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request expectations and local
+validation details.