docs: reorganize documentation and establish branch governance

.github/workflows/feature-ci.yml

@@ -0,0 +1,54 @@
+name: Feature checks
+
+on:
+  push:
+    branches:
+      - "feature/**"
+  pull_request:
+    branches:
+      - develop
+
+permissions:
+  contents: read
+
+concurrency:
+  group: feature-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  feature-source-policy:
+    name: feature-source-policy
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require a feature branch source
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          case "$HEAD_REF" in
+            feature/*) ;;
+            *)
+              echo "Pull requests into develop must come from feature/* branches."
+              exit 1
+              ;;
+          esac
+
+  feature-typescript:
+    name: feature-typescript
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Type-check
+        run: npm run typecheck
+      - name: Run default tests
+        run: npm test -- --reporter=dot

.github/workflows/integration-ci.yml

@@ -0,0 +1,70 @@
+name: Integration checks
+
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: integration-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  integration-source-policy:
+    name: integration-source-policy
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require the develop branch source
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          if [ "$HEAD_REF" != "develop" ]; then
+            echo "Pull requests into main must come from develop."
+            exit 1
+          fi
+
+  integration-typescript:
+    name: integration-typescript
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Type-check
+        run: npm run typecheck
+      - name: Run default tests
+        run: npm test -- --reporter=dot
+      - name: Build embedded entry
+        run: npm run build:embedded
+      - name: Verify npm package contents
+        run: npm pack --dry-run
+
+  integration-rust:
+    name: integration-rust
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: rust
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+      - name: Run Rust workspace tests
+        run: cargo test --workspace -- --skip web_fetch_returns_error_for_unreachable_url

AGENTS.md

@@ -0,0 +1,68 @@
+# Repository Agent Guide
+
+## Scope
+
+These instructions apply to repository maintenance and development. They are not runtime prompt content. The workspace prompt template used by Lumin agents is `templates/base/AGENTS.md`.
+
+## Start Here
+
+- `docs/README.md` is the documentation index and lifecycle policy.
+- `docs/reference/` contains current external contracts.
+- `docs/architecture/` contains implementation structure and invariants.
+- `docs/operations/` contains dated project and verification status.
+- `docs/archive/` contains historical evidence only.
+
+When prose conflicts with implementation, prefer source code, runtime schemas, and reproducible tests. Use archived files only to understand earlier decisions.
+
+## Repository Map
+
+- `src/`: primary TypeScript runtime.
+- `src/loop/` and `src/task/`: single/dual execution and task lifecycle.
+- `src/embedded.ts`: Node-free embedded entry; keep its dependency graph platform-neutral.
+- `rust/crates/`: partially aligned Rust runtime and server.
+- `tests/`: default, real-LLM, capability, parity, and benchmark tests.
+- `templates/`: files copied into user workspaces.
+- `scripts/`: build and verification helpers.
+
+## Working Rules
+
+- Inspect the relevant source and tests before changing behavior or documentation.
+- Preserve unrelated and pre-existing worktree changes.
+- Search with `rg`/`rg --files`; make focused, reviewable edits.
+- Do not manually edit generated or local-state directories: `dist/`, `node_modules/`, `rust/target/`, or `workspace/`.
+- Do not claim TypeScript/Rust parity without checking the exact capability on both sides.
+- Do not treat dual-loop `processMessage()` as a final-result call; it returns task creation/queueing state.
+- Keep Node APIs out of the embedded entry and its transitive imports.
+- Keep root/developer instructions out of `templates/base/AGENTS.md`.
+
+## Branch and Release Policy
+
+- Begin each change from an updated `develop` and create a focused `feature/<topic>` branch.
+- Do not commit or push directly to `develop` or `main`; both are protected long-lived branches.
+- Before opening a pull request into `develop`, run `npm run typecheck` and `npm test -- --reporter=dot` and address failures rather than bypassing checks.
+- Merge feature pull requests into `develop` with squash merge after Feature CI succeeds.
+- Use `develop → main` as the only release promotion path. Integration CI must succeed before the release pull request is merged.
+- Never force-push or delete `develop` or `main`, and never disable or override required checks to complete a merge.
+
+## Documentation Rules
+
+- Keep `docs/README.md` as the only top-level document under `docs/`.
+- Put API contracts in `docs/reference/`, architecture in `docs/architecture/`, and dated engineering evidence in `docs/operations/`.
+- Put completed designs, plans, analyses, and measurements under `docs/archive/`.
+- Repair inbound and cross-document links whenever a document moves.
+- Do not silently modernize historical commands or conclusions inside archived records.
+- Avoid copying volatile test totals or protocol schemas into multiple entry documents; link to the authoritative current document.
+
+## Verification
+
+For TypeScript or documentation changes, start with:
+
+```bash
+npm run typecheck
+npm test -- --reporter=dot
+git diff --check
+```
+
+Also run `npm run build:embedded` when changing the embedded dependency graph or exports. Run the relevant Cargo command when changing Rust. Real-LLM and capability suites require explicit credentials/flags; skipped tests are not successful capability verification.
+
+Before handing off, report the commands actually run, skipped or environment-sensitive cases, and whether changes remain uncommitted.