fawxai · abbudjoe · Apr 3, 2026 · Apr 3, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -4,7 +4,7 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, staging ]
 
 env:
   CARGO_TERM_COLOR: always
@@ -40,6 +40,8 @@ jobs:
       - name: Cargo check
         run: cargo check --workspace --all-targets
 
+      - name: Cargo check (oauth-bridge feature)
+        run: cargo check -p fx-cli --features oauth-bridge --all-targets
 
   test:
     name: Test
@@ -62,6 +64,8 @@ jobs:
       - name: Run tests
         run: cargo test --workspace
 
+      - name: Run tests (oauth-bridge feature)
+        run: cargo test -p fx-cli --features oauth-bridge
 
   clippy:
     name: Clippy
@@ -86,6 +90,8 @@ jobs:
       - name: Run clippy
         run: cargo clippy --workspace --all-targets -- -D warnings
 
+      - name: Run clippy (oauth-bridge feature)
+        run: cargo clippy -p fx-cli --features oauth-bridge --all-targets -- -D warnings
 
   fmt:
     name: Format
@@ -100,3 +106,23 @@ jobs:
 
       - name: Check formatting
         run: cargo fmt --all --check
+
+  ci_checks:
+    name: CI Checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: |
+          if ! command -v shellcheck >/dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install -y shellcheck
+          fi
+
+      - name: Shellcheck CI scripts
+        run: shellcheck scripts/spec-tests/ci-workflow-cache-paths-check.sh
+
+      - name: Verify workflow cache path safety
+        run: ./scripts/spec-tests/tests/ci-workflow-cache-paths-test.sh
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -130,8 +130,8 @@ Fawx skills are WASM modules that extend the engine's capabilities. To create
 a new skill:
 
 1. Use the skill template: `cargo generate fawxai/skill-template`
-2. Implement the `Skill` trait
-3. Test locally with `fawx skill install --path ./target/wasm32-wasi/release/`
+2. Build and install locally with `fawx skill build .`
+3. Test a prebuilt artifact with `fawx skill install ./target/wasm32-wasip1/release/<skill>.wasm`
 4. Publish to the marketplace (coming soon)
 
 See [docs/skills/](docs/skills/) for the full SDK reference.

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/ENGINEERING.md b/ENGINEERING.md
@@ -203,11 +203,13 @@ feature/* → dev → staging → main
 
 - **feature branches**: cut from `dev`, PRs target `dev`
 - **dev**: integration branch — merge freely after CI + TUI smoke test pass. Multiple features tested together here.
-- **staging**: release candidate — maintainer promotes `dev → staging` after integration testing passes
+- **staging**: release candidate — Joe manually promotes `dev → staging` after integration testing passes
 - **main**: production releases only — `staging → main` for releases
 
 All three long-lived branches are protected: no force push, no deletion.
 
 ---
 
-*This file defines the engineering standards for the Fawx codebase. All contributions are held to these rules. For style preferences, see `TASTE.md`.*
+---
+
+*This file is immutable doctrine. Cite it in PR reviews. Changes require explicit user approval. For evolving preferences and style, see `TASTE.md`.*
diff --git a/README.md b/README.md
@@ -13,15 +13,16 @@ Fawx is a local-first agentic engine. It runs on your machine, calls LLMs for re
 ## Quick Start
 
 ```bash
+# Build
 git clone https://github.com/fawxai/fawx.git
-cd fawx
-./scripts/install.sh
+cd fawx && cargo build --release
 
-fawx setup
-fawx serve
-```
+# Configure (interactive wizard)
+./target/release/fawx setup
 
-This builds from source, installs the `fawx` binary to `~/.local/bin/`, and walks you through configuration. Set `INSTALL_DIR` to change the install location.
+# Run
+./target/release/fawx serve
+```
 
 Bring your own API key (Anthropic, OpenAI, or local models). Fawx never sends data anywhere except the LLM provider you choose.
 
@@ -102,7 +103,7 @@ WASM skills extend Fawx's capabilities. Each skill runs in a sandboxed WebAssemb
 
 ## WASM Skills
 
-Skills are Rust crates compiled to WebAssembly. The [skill marketplace](https://github.com/fawxai) has ready-to-install skills. Building your own takes minutes:
+Skills are Rust crates compiled to WebAssembly. The recommended local-dev workflow is `fawx skill build <project>`: it builds the project for `wasm32-wasip1`, installs it into `~/.fawx/skills/`, and signs it when a signing key is present.
 
 ```rust
 #[no_mangle]
@@ -114,13 +115,29 @@ pub extern "C" fn run() {
 ```
 
 ```bash
-# Install a skill
-fawx skill install fawxai/skill-web-search
-
-# Or build your own
+# Recommended local-dev workflow
 cargo generate fawxai/skill-template
-cargo build --release --target wasm32-unknown-unknown
-fawx skill install ./target/wasm32-unknown-unknown/release/my_skill.wasm
+cd my-skill
+fawx skill build .
+```
+
+Use the other paths when they match your input:
+
+- `fawx skill build <project>` is the canonical local-dev path for a custom skill project.
+- `skills/build.sh --install` is the repo maintainer path for the built-in `skills/` collection.
+- `fawx skill install <path>` is the artifact path for a prebuilt `.wasm` file or skill directory.
+- `fawx keys generate` creates a local signing keypair and trusts the matching public key for local verification.
+- `fawx sign <skill>` signs an already-installed skill when it still needs a signature.
+
+If you generate or trust a key while the server is already running, restart it before expecting the loaded skill state to flip from `invalid` to `valid`.
+
+```bash
+# Prebuilt local artifact
+cargo build --release --target wasm32-wasip1
+fawx skill install ./target/wasm32-wasip1/release/my_skill.wasm
+
+# Built-in repo skills collection
+skills/build.sh --install
 ```
 
 Available skills: [web search](https://github.com/fawxai/skill-brave-search) · [web fetch](https://github.com/fawxai/skill-web-fetch) · [scheduler](https://github.com/fawxai/skill-scheduler) · weather · vision · TTS · STT · browser · canvas

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,23 @@
+# Fawx Documentation
+
+## Reference
+
+| Document | Description |
+|----------|-------------|
+| [WASM_SKILLS.md](WASM_SKILLS.md) | WASM skill system design and authoring guide |
+
+## Repo Root Docs
+
+- [`ENGINEERING.md`](../ENGINEERING.md) — Development doctrine
+- [`ARCHITECTURE.md`](../ARCHITECTURE.md) — System architecture overview
+- [`TASTE.md`](../TASTE.md) — Style and design preferences
+- [`DOCTRINE.md`](../DOCTRINE.md) — Runtime invariants
+- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — Contribution guide
+
+## Legal
+
+- [CLA (Individual)](legal/CLA-individual.md)
+- [CLA (Corporate)](legal/CLA-corporate.md)
+- [Terms of Service](legal/terms-of-service.md)
+- [Privacy Policy](legal/privacy-policy.md)
+- [EULA](legal/eula.md)
diff --git a/docs/WASM_SKILLS.md b/docs/WASM_SKILLS.md
@@ -48,33 +48,23 @@ Skills declare required capabilities in their manifest:
 - `storage` - Persistent key-value storage
 - `notifications` - Send user notifications
 - `sensors` - Read sensor data (location, accelerometer, etc.)
-- `phone_actions` - Control phone functions (high privilege)
 
 Capabilities are enforced at runtime. Skills cannot access resources they haven't declared.
 
 ## Skill Lifecycle
 
-### Development
+### Recommended Workflows
 
-1. Write skill in Rust (or other WASM language)
-2. Implement `run()` entry point
-3. Use host API functions via `extern "C"` imports
-4. Compile to `wasm32-wasi` target
-5. Create `manifest.toml`
-
-### Installation
-
-```bash
-fawx skill install path/to/skill-directory
-# or
-fawx skill install path/to/skill.wasm
-```
-
-Installation:
-- Validates manifest
-- Verifies WASM module compiles
-- Copies to `~/.fawx/skills/{skill-name}/`
-- Optionally verifies signature
+- Local dev project: `fawx skill build <project>`
+  - Canonical local-dev path for a custom skill project
+  - Builds for `wasm32-wasip1`
+  - Installs into `~/.fawx/skills/{skill-name}/`
+  - Signs automatically when a signing key exists
+- Prebuilt artifact: `fawx skill install <path>`
+  - Use for a prebuilt `.wasm` file or skill directory
+- Built-in repo skills: `skills/build.sh --install`
+  - Specialized repo maintainer path for the built-in `skills/` collection
+- Already-installed skill that still needs a signature: `fawx sign <skill>` or `fawx sign --all`
 
 ### Discovery
 
@@ -164,16 +154,17 @@ pub extern "C" fn run() {
 }
 ```
 
-### Build
+### Build And Install
 
 ```bash
-cargo build --target wasm32-wasi --release
+fawx skill build .
 ```
 
-### Install
+### Prebuilt Artifact Install
 
 ```bash
-fawx skill install target/wasm32-wasi/release/calculator_skill.wasm
+cargo build --target wasm32-wasip1 --release
+fawx skill install target/wasm32-wasip1/release/calculator_skill.wasm
 ```
 
 ### Use
@@ -287,13 +278,26 @@ Installed skills:
     Capabilities: network, storage
 ```
 
-### Install Skill
+### Recommended Local Dev
+
+```bash
+fawx skill build ./skills/calculator-skill
+```
+
+### Install Prebuilt Skill
 
 ```bash
 fawx skill install skills/calculator-skill
 fawx skill install skills/calculator-skill/calculator.wasm
 ```
 
+### Sign Installed Skill
+
+```bash
+fawx sign calculator
+fawx sign --all
+```
+
 ### Remove Skill
 
 ```bash
@@ -324,7 +328,7 @@ fawx skill remove calculator
 - Check manifest is valid TOML
 - Verify API version is `host_api_v1`
 - Ensure WASM file is present
-- Check compilation target is `wasm32-wasi`
+- Check compilation target is `wasm32-wasip1`
 
 ### Runtime Errors
 

diff --git a/engine/crates/fawx-test/scenarios/file-read.toml b/engine/crates/fawx-test/scenarios/file-read.toml
@@ -1,7 +1,7 @@
 [scenario]
 name = "file_read"
 description = "Fawx reads a file using the read_file tool and reports its content"
-timeout_seconds = 30
+timeout_seconds = 120
 
 [setup]
 files = [

diff --git a/engine/crates/fawx-test/scenarios/memory-write.toml b/engine/crates/fawx-test/scenarios/memory-write.toml
@@ -1,7 +1,7 @@
 [scenario]
 name = "memory_write"
 description = "Fawx writes to memory when asked to remember something"
-timeout_seconds = 45
+timeout_seconds = 120
 
 [setup]
 files = []
@@ -11,5 +11,5 @@ prompt = "Remember that my favorite color is blue"
 
 [expect]
 tool_calls = ["memory_write"]
-output_contains = ["blue"]
+tool_input_contains = ["blue"]
 output_not_contains = ["error"]