coding-os 0.3.2__py3-none-any.whl

templates/react-native/skills/react-native-patterns/references/list-performance.md

@@ -0,0 +1,70 @@
+<!-- domain:MOBILE | layer:reference | ssot:true | updated:2026-06-04 -->
+# React Native List & Render Performance
+
+> P: Keep scroll at 60fps and avoid the re-render cascades that make RN feel slow.
+> R: Building any list screen or a component that re-renders often.
+> S: Cross-platform mobile concerns (navigation, offline) — that's mobile-fundamentals.
+> N: [SKILL.md](../SKILL.md), [rn-review-checklist.md](../assets/rn-review-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Never ScrollView a long list
+
+```tsx
+// Wrong — renders ALL items up front; janky + memory-heavy
+<ScrollView>{items.map((i) => <Row key={i.id} item={i} />)}</ScrollView>
+
+// Correct — virtualized: renders only what's visible
+<FlatList data={items} keyExtractor={(i) => i.id} renderItem={renderRow} />
+```
+
+`ScrollView` mounts every child; `FlatList` (or Shopify `FlashList`, faster)
+virtualizes. `FlashList` needs an `estimatedItemSize` and recycles views — prefer
+it for large/heterogeneous lists.
+
+## Stable renderItem + keyExtractor
+
+```tsx
+// Wrong — new function identity each render defeats memoization
+<FlatList renderItem={({ item }) => <Row item={item} />} />
+
+// Correct — hoisted, memoized item
+const Row = React.memo(({ item }) => <Text>{item.name}</Text>);
+const renderRow = useCallback(({ item }) => <Row item={item} />, []);
+<FlatList data={data} keyExtractor={(i) => i.id} renderItem={renderRow} />
+```
+
+`React.memo` the row, `useCallback` the renderItem, and give a real
+`keyExtractor` — without it RN uses array index keys and re-renders on reorder.
+`scan_rn_perf.py` flags inline renderItem, missing keyExtractor, and inline styles.
+
+## StyleSheet, not inline objects
+
+```tsx
+// Wrong — new style object every render
+<View style={{ padding: 16 }} />
+
+// Correct — created once
+const styles = StyleSheet.create({ box: { padding: 16 } });
+<View style={styles.box} />
+```
+
+`StyleSheet.create` returns stable references (and historically an id passed over
+the bridge). Inline style objects are a fresh reference each render → the child
+re-renders.
+
+## Animations on the UI thread (Reanimated)
+
+Run animations with **Reanimated** worklets so they execute on the UI thread, not
+the JS thread — a busy JS thread won't drop the animation. `useSharedValue` +
+`useAnimatedStyle` keep the frame loop off JS. The old `Animated` API with
+`useNativeDriver: true` covers transform/opacity; layout-driving animation needs
+Reanimated.
+
+## Diagnose
+
+Hermes is the default engine (faster startup, less memory). Profile with Flipper /
+the React DevTools profiler / `react-native-performance`; watch for: long lists
+without virtualization, components re-rendering on unrelated state, large images
+not resized, and bridge chatter (batch native calls). Measure before optimizing —
+the slow thing is often not where you guess.

templates/react-native/skills/react-native-patterns/scripts/scan_rn_perf.py

@@ -0,0 +1,77 @@
+"""Flag React Native list/render performance smells.
+
+PURPOSE:      Catch the RN-specific perf footguns (inline renderItem, missing
+              keyExtractor, ScrollView for long lists) that tank scroll FPS.
+INPUT:        one or more .tsx/.jsx files. [--json]
+OUTPUT:       Findings (file:line) on stderr; "clean"/"N finding(s)" on stdout.
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only (regex). Heuristic — pairs with eslint + Flipper.
+NOTES:        Pure scan_text() is unit-testable. Spec:
+              docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+LINE_RULES: list[tuple[re.Pattern, str]] = [
+    (
+        re.compile(r"renderItem=\{\s*\([^)]*\)\s*=>"),
+        "inline renderItem arrow — new function each render; hoist + useCallback",
+    ),
+    (
+        re.compile(r"<(FlatList|FlashList|SectionList)\b(?![^>]*keyExtractor)", re.DOTALL),
+        "list without keyExtractor — falls back to index keys; provide a stable id",
+    ),
+    (
+        re.compile(r"style=\{\{"),
+        "inline style object — new reference each render; StyleSheet.create or hoist",
+    ),
+    (
+        re.compile(r"<ScrollView\b[^>]*>\s*\{[^}]*\.map\("),
+        "ScrollView rendering a mapped list — renders all items; use FlatList/FlashList",
+    ),
+]
+
+
+def scan_text(text: str, *, filename: str = "?") -> list[str]:
+    findings: list[str] = []
+    for n, line in enumerate(text.splitlines(), 1):
+        stripped = line.lstrip()
+        if stripped.startswith(("//", "*", "/*")):
+            continue
+        for pattern, msg in LINE_RULES:
+            if pattern.search(line):
+                findings.append(f"{filename}:{n}: {msg}")
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    all_findings: list[str] = []
+    for path in args.files:
+        try:
+            all_findings.extend(scan_text(Path(path).read_text(encoding="utf-8"), filename=path))
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+
+    for f in all_findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": all_findings, "count": len(all_findings)}))
+    else:
+        print("clean" if not all_findings else f"{len(all_findings)} finding(s)")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

templates/react-native/stack.yaml

@@ -0,0 +1,70 @@
+version: 1
+id: react-native
+language: typescript
+label: "React Native + Expo + TypeScript"
+category: mobile
+
+structure:
+  root: src/mobile
+  tree: |
+    src/mobile/
+    ├── screens/
+    ├── components/
+    ├── navigation/
+    └── hooks/
+  notes: "Expo bare-compatible; state per state-management skill hierarchy"
+primary_skill: react-native-mobile
+skills: [react-native-mobile, react-native-patterns]
+
+# These substitution keys are joined across stacks by the aggregator via
+# _derive_substitutions (joined on " | "). VERIFY_MOBILE_* override the
+# "(none)" defaults from base.yaml.
+substitutions:
+  DOMAIN_ROUTES: "Mobile→`docs/playbooks/mobile-app.md`"
+  SKILL_ROUTES: "Mobile→`react-native-mobile`"
+  ENGINEERING_RULE_ROUTING: "Mobile→`docs/engineering/mobile-rules.md`, Offline→`docs/engineering/offline-first.md`, a11y→`docs/engineering/accessibility-mobile.md`"
+  TOOL_ROUTING_IMPL: "`lint-mobile`, `test-mobile`, `build-mobile`"
+  VERIFY_MOBILE_GLOB: "`src/mobile/`"
+  VERIFY_MOBILE_SUITES: "lint-mobile + test-mobile"
+  VERIFY_MOBILE: "`cd src/mobile && npm run lint && npm test`"
+  QUICK_ROUTING: |-
+    - Mobile screen / component task → [Mobile App Playbook](./playbooks/mobile-app.md)
+    - Native module / bridge work → [Mobile App Playbook](./playbooks/mobile-app.md)
+    - Offline / sync feature → [Mobile App Playbook](./playbooks/mobile-app.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-MOBILE` → `./playbooks/mobile-app.md`
+    - `REF:MOBILE-RULES` → `./engineering/mobile-rules.md`
+    - `REF:OFFLINE-FIRST` → `./engineering/offline-first.md`
+    - `REF:A11Y` → `./engineering/accessibility-mobile.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-MOBILE", path: "./playbooks/mobile-app.md",            desc: "Mobile app playbook"}
+  - {code: "REF:MOBILE-RULES",    path: "./engineering/mobile-rules.md",        desc: "Mobile engineering rules"}
+  - {code: "REF:OFFLINE-FIRST",   path: "./engineering/offline-first.md",       desc: "Offline-first patterns"}
+  - {code: "REF:A11Y",            path: "./engineering/accessibility-mobile.md", desc: "Accessibility checklist"}
+
+routing_entries:
+  - "Mobile screen / component task → [Mobile App Playbook](./playbooks/mobile-app.md)"
+  - "Offline / sync feature → [Mobile App Playbook](./playbooks/mobile-app.md)"
+
+rules:
+  - {file: rules/mobile.md, globs: ["src/mobile/**/*.{ts,tsx}"]}
+
+dimensions:
+  - {name: "RN screen",         read_files: ["docs/playbooks/mobile-app.md", "docs/engineering/mobile-rules.md"]}
+  - {name: "RN component",      read_files: ["docs/engineering/mobile-rules.md"]}
+  - {name: "Offline / sync",    read_files: ["docs/engineering/offline-first.md", "docs/playbooks/mobile-app.md"]}
+  - {name: "Native bridge",     read_files: ["docs/playbooks/mobile-app.md"]}
+  - {name: "Accessibility",     read_files: ["docs/engineering/accessibility-mobile.md"]}
+
+skill_enforcement:
+  - {globs: ["src/mobile/**/*.{ts,tsx}"], primary: react-native-mobile, secondary: [clean-code, frontend-fundamentals, mobile-fundamentals, a11y]}
+  - {globs: ["src/mobile/**/components/**/*.{ts,tsx}", "src/mobile/**/screens/**/*.{ts,tsx}"], primary: react-native-patterns, secondary: [clean-code, react-native-mobile, state-management, performance]}
+
+makefile_targets:
+  - {name: lint-mobile,  cmd: "cd src/mobile && npm run lint"}
+  - {name: test-mobile,  cmd: "cd src/mobile && npm test"}
+  - {name: build-mobile, cmd: "cd src/mobile && npm run build"}
+
+verify:
+  - {glob: "src/mobile/**/*.{ts,tsx}", suites: "lint-mobile + test-mobile", cmd: "cd src/mobile && npm run lint && npm test"}

templates/ruby-plain/scaffold/src/backend/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+ruby "3.3.0"
+
+group :development, :test do
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.60", require: false
+end

templates/ruby-plain/scaffold/src/backend/main.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+puts "{{PROJECT_NAME}} — scaffolded by coding-os (ruby-plain)"

templates/ruby-plain/scaffold-boundary.yaml

@@ -0,0 +1,23 @@
+# Scaffold boundary for the ruby-plain stack (stdlib + Bundler).
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: ruby-plain
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.rb"
+  - "src/backend/Gemfile"
+
+imports_from:
+  - src/shared/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Plain Ruby — Gemfile lives in src/backend/. The rails framework stack replaces this layout."

templates/ruby-plain/stack.yaml

@@ -0,0 +1,50 @@
+version: 1
+id: ruby-plain
+language: ruby
+label: "Ruby (plain — stdlib + Bundler, no framework)"
+category: backend
+primary_skill: null
+skills: []
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── Gemfile
+    ├── main.rb
+    └── lib/             # grow into lib/-centric layout as the gem grows
+  notes: "plain Ruby — Gemfile + a runnable main.rb; lib/ holds reusable modules. Framework stacks (rails) replace this layout."
+
+# Plain-language stack (template-authoring.md § Language layer): picked when
+# the user chooses "ruby" without a framework. Ships a runnable skeleton and
+# the verify wiring; the rails stack extends the language with its conventions.
+
+substitutions:
+  DOMAIN_ROUTES: "Ruby library / CLI task → AGENTS.md critical rules"
+  SKILL_ROUTES: "Ruby → `clean-code` (generic) + `thinking_os` (kernel)"
+  ENGINEERING_RULE_ROUTING: "Ruby → AGENTS.md critical rules + `docs/governance/`"
+  TOOL_ROUTING_IMPL: "`lint-ruby`, `test-ruby`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-ruby + test-ruby"
+  VERIFY_BACKEND: "`cd src/backend && bundle exec rubocop && bundle exec rspec`"
+  QUICK_ROUTING: |-
+    - Ruby module / CLI task → see AGENTS.md critical rules
+  STACK_REF_CODES: ""
+
+ref_codes: []
+
+routing_entries:
+  - "Ruby library / CLI task → see AGENTS.md critical rules"
+
+rules: []
+
+makefile_targets:
+  - {name: lint-ruby, cmd: "cd src/backend && bundle exec rubocop"}
+  - {name: test-ruby, cmd: "cd src/backend && bundle exec rspec"}
+
+verify:
+  - {glob: "src/backend/**/*.rb", suites: "lint-ruby + test-ruby", cmd: "cd src/backend && bundle exec rubocop && bundle exec rspec"}
+
+dimensions: []
+
+skill_enforcement: []

templates/rust-axum/rules/backend.md

@@ -0,0 +1,20 @@
+---
+globs: ["src/backend/**/*.rs"]
+alwaysApply: false
+---
+
+# Rust + Axum Backend Rules (auto-loaded on src/backend/**/*.rs)
+
+When editing any Rust file under `src/backend/`, follow these standards:
+
+- **Handlers are thin async fns** returning `Result<T, AppError>` — parse via an extractor, call one service method, return the value. Axum serializes; never hand-build the response envelope.
+- **One error shaper** — the central `AppError` (in `error.rs`) implements `IntoResponse`; it is the ONLY place that writes an error body. Handlers `?`-propagate; they never `match` to build error JSON.
+- **Errors propagate with `?`, never `.unwrap()`/`.expect()`** in request paths — convert with `From`/`thiserror` into `AppError`. `.unwrap()` is allowed only at startup where a failure should abort the process.
+- **Extractors validate fail-closed** — `Json<Dto>`/`Query<Dto>` reject malformed input before the handler body runs; a handler never reads the raw request.
+- **Tower middleware lives in `app.rs`** as `.layer(...)` calls on the router — never inside an individual handler.
+- **Shared state is `Arc<AppState>`** injected via `State<…>`; no global mutable statics.
+- **Tests** — `#[tokio::test]` calling the router via `tower::ServiceExt::oneshot`; one happy + one error path per route minimum.
+
+Canonical policy: `docs/engineering/rust-axum-rules.md`
+Playbook: `docs/playbooks/rust-axum-service.md`
+Primary skill: `rust`

templates/rust-axum/scaffold/docs/engineering/rust-axum-rules.md

@@ -0,0 +1,35 @@
+<!-- domain:BACKEND | layer:rules | ssot:true | updated:{{DATE}} -->
+# Rust + Axum Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} Rust + Axum backend.
+Read when: Editing anything under `src/backend/`.
+Skip when: Frontend/mobile work.
+Read next: [Rust + Axum Service Playbook](../playbooks/rust-axum-service.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Thin handlers** — a handler extracts, calls one service method, returns the
+   value as `Result<_, AppError>`. Business logic in a handler is a
+   build-blocking review finding (the layer table in the `rust` skill is the SSOT).
+2. **One error shaper** — only `AppError`'s `IntoResponse` impl writes an error
+   body; it logs full detail and returns the problem shape with no internals
+   (no panics, no driver messages, no backtraces to the client).
+3. **No panics in request paths** — `.unwrap()`/`.expect()`/`panic!` are forbidden
+   off the startup path; propagate with `?` and convert via `From`/`thiserror`.
+   `unwrap` is acceptable only in `main` where failure should abort the process.
+4. **Validation fail-closed** — every input is an extractor-validated `serde`
+   DTO; an unvalidated body never reaches a service.
+5. **Transport-free services** — the service layer imports no `axum` types so it
+   stays unit-testable and a transport swap is a handler-only change.
+6. **Shared state via `State<Arc<…>>`** — no global mutable statics; clone the
+   `Arc`, never the inner value.
+7. **Clippy is the lint gate** — `cargo clippy -- -D warnings` must pass;
+   `unsafe` and `#[allow(...)]` require a written justification at the site.
+
+## Testing bar
+
+Services ≥ unit-tested per public method; handlers ≥ happy + error path driven
+through the router via `tower::ServiceExt::oneshot` (no bound port); repositories
+integration-tested against a disposable database. `cargo test` is the gate.

templates/rust-axum/scaffold/docs/playbooks/rust-axum-service.md

@@ -0,0 +1,43 @@
+<!-- domain:BACKEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Rust + Axum Service Playbook
+
+Purpose: The end-to-end recipe for adding or changing an Axum endpoint in {{PROJECT_NAME}}.
+Read when: Any task that adds a handler, route, extractor, tower middleware layer, or error variant.
+Skip when: Pure infra/devops work — see the deployment docs.
+Read next: [Rust + Axum Engineering Rules](../engineering/rust-axum-rules.md), [Error Format](../api-contracts/error-format.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add an endpoint (the only sanctioned path)
+
+1. **Contract first** — define the request/response types as `serde` structs;
+   error cases map to an `AppError` variant ([error-format](../api-contracts/error-format.md)).
+2. **Handler** — `src/backend/src/routes/<feature>.rs`: an async fn that takes
+   extractors (`Json<Dto>`, `Path<_>`, `State<_>`) and returns
+   `Result<Json<_>, AppError>`. Call one service method, return the value.
+3. **Validate at the extractor** — a malformed body is rejected by the
+   `Json<Dto>` extractor before the handler body runs; never read the raw request.
+4. **Service** — business logic lives in a transport-free module that knows
+   nothing about `axum` types; it returns domain `Result`s the handler maps via `?`.
+5. **Wire** — register the route in `app.rs`
+   (`.route("/<feature>", post(<feature>::create))`).
+6. **Error** — propagate with `?`; add a new `AppError` variant + `From` impl if a
+   new failure category needs a distinct status. Never build error JSON in a handler.
+7. **Test** — `#[tokio::test]` driving the router via `ServiceExt::oneshot`
+   (happy + error path), plus pure unit tests on the service.
+8. **Verify** — `cd src/backend && cargo clippy -- -D warnings && cargo test`.
+
+## Global wiring (set once in `app.rs` / `main.rs`)
+
+Routes + tower middleware are assembled in `app.rs::router()`; `main.rs` only
+builds the tracing subscriber, binds the listener, and calls `axum::serve`. Add
+cross-cutting concerns (tracing, timeout, CORS) as `.layer(...)` on the router —
+never inside a handler.
+
+## Anti-patterns
+
+- Error JSON built inside a handler — the `AppError` `IntoResponse` impl owns the shape.
+- `.unwrap()` / `.expect()` in a request path — propagate with `?`; `unwrap` is for startup only.
+- A handler importing the service's DB client directly — keep the service transport-free.
+- `.layer(...)` middleware applied per handler — middleware belongs on the router in `app.rs`.
+- A global mutable `static` for shared state — use `State<Arc<AppState>>`.

templates/rust-axum/scaffold/src/backend/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "{{PROJECT_NAME}}-backend"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+axum = "0.7"
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+tower = "0.5"
+tower-http = { version = "0.6", features = ["trace"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "1"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+
+[dev-dependencies]
+tower = { version = "0.5", features = ["util"] }
+http-body-util = "0.1"

templates/rust-axum/scaffold/src/backend/src/app.rs

@@ -0,0 +1,12 @@
+use axum::{routing::get, Router};
+use tower_http::trace::TraceLayer;
+
+use crate::routes::health;
+
+// Single place that assembles routes + tower middleware layers.
+// Handlers own no wiring; middleware lives here, never inside a handler.
+pub fn router() -> Router {
+    Router::new()
+        .route("/health", get(health::check))
+        .layer(TraceLayer::new_for_http())
+}

templates/rust-axum/scaffold/src/backend/src/error.rs

@@ -0,0 +1,48 @@
+use axum::{
+    http::StatusCode,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde_json::json;
+
+// The ONE central error type. Handlers `?`-propagate into this; its
+// IntoResponse impl is the only place an error body is shaped
+// (RFC 9457 problem shape per docs/api-contracts/error-format.md).
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error("{0}")]
+    NotFound(String),
+    #[error("{0}")]
+    BadRequest(String),
+    #[error("internal error")]
+    Internal(#[from] anyhow_like::Error),
+}
+
+// Minimal stand-in so the skeleton compiles without an extra crate;
+// real services use anyhow / a domain error and a richer From chain.
+pub mod anyhow_like {
+    #[derive(Debug, thiserror::Error)]
+    #[error("{0}")]
+    pub struct Error(pub String);
+}
+
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let (status, title) = match &self {
+            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg.clone()),
+            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
+            // Full detail to the log only; never internals to the client.
+            AppError::Internal(err) => {
+                tracing::error!(error = %err, "internal error");
+                (StatusCode::INTERNAL_SERVER_ERROR, "Internal Server Error".to_string())
+            }
+        };
+
+        let body = Json(json!({
+            "type": "about:blank",
+            "title": title,
+            "status": status.as_u16(),
+        }));
+        (status, body).into_response()
+    }
+}

templates/rust-axum/scaffold/src/backend/src/main.rs

@@ -0,0 +1,24 @@
+use std::net::SocketAddr;
+
+mod app;
+mod error;
+mod routes;
+
+#[tokio::main]
+async fn main() {
+    tracing_subscriber::fmt()
+        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
+        .init();
+
+    let addr: SocketAddr = std::env::var("BIND_ADDR")
+        .unwrap_or_else(|_| "0.0.0.0:3000".to_string())
+        .parse()
+        .expect("BIND_ADDR must be a valid socket address");
+
+    let listener = tokio::net::TcpListener::bind(addr)
+        .await
+        .expect("failed to bind listener");
+
+    tracing::info!("{{PROJECT_NAME}} backend listening on {addr}");
+    axum::serve(listener, app::router()).await.expect("server error");
+}

templates/rust-axum/scaffold/src/backend/src/routes/health.rs

@@ -0,0 +1,37 @@
+use axum::Json;
+use serde::Serialize;
+
+use crate::error::AppError;
+
+#[derive(Serialize)]
+pub struct Health {
+    status: &'static str,
+}
+
+// Thin handler: no logic, returns Result so the error path flows through
+// the central AppError shaper like every other route.
+pub async fn check() -> Result<Json<Health>, AppError> {
+    Ok(Json(Health { status: "ok" }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::app;
+    use axum::body::Body;
+    use axum::http::{Request, StatusCode};
+    use http_body_util::BodyExt;
+    use tower::ServiceExt;
+
+    #[tokio::test]
+    async fn health_returns_ok() {
+        let response = app::router()
+            .oneshot(Request::builder().uri("/health").body(Body::empty()).unwrap())
+            .await
+            .unwrap();
+
+        assert_eq!(response.status(), StatusCode::OK);
+        let bytes = response.into_body().collect().await.unwrap().to_bytes();
+        assert_eq!(&bytes[..], br#"{"status":"ok"}"#);
+    }
+}

templates/rust-axum/scaffold/src/backend/src/routes/mod.rs

@@ -0,0 +1,2 @@
+// One module per domain. Routers are assembled in app.rs.
+pub mod health;

templates/rust-axum/scaffold-boundary.yaml

@@ -0,0 +1,25 @@
+# Scaffold boundary for the rust-axum stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: rust-axum
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.rs"
+  - "src/backend/**/Cargo.toml"
+
+imports_from:
+  - src/shared/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Cargo workspace root is src/backend/ (Cargo.toml lives there)."
+  - "Handlers thin; one AppError implementing IntoResponse is the only error-response shaper."
+  - "Tower middleware is layered in app.rs, never inside individual handlers."

templates/rust-axum/skills/rust/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: rust
+tier: stack
+domain: [backend]
+description: Use when creating or modifying Rust files under src/backend/ in an Axum service — handlers, the router (app.rs), extractors/DTOs, the central AppError IntoResponse error shaper, tower middleware layers, Arc<AppState> shared state, and their tokio tests. Triggers on any .rs change under src/backend/. Covers thin async handlers returning Result<T, AppError>, ?-propagation over unwrap, fail-closed extractor validation, the single IntoResponse error shaper, and router testing via tower oneshot. Generic backend design lives in backend-fundamentals.
+globs: "src/backend/**/*.rs"
+depends_on:
+  - clean-code
+  - backend-fundamentals
+  - api-design
+last_reviewed: "2026-06-14"
+---
+
+REQUIRED BACKGROUND: You MUST also follow the core `backend-fundamentals` skill (request lifecycle, layering, idempotency) and `clean-code` (fail-closed errors, self-documenting code, error-path tests). This skill adds ONLY Rust + Axum-specific patterns on top; `api-design` governs the public contract.
+
+# rust
+
+## Layer contract (matches `structure.tree`) — the SSOT for layering
+
+| Layer | May import | Never |
+|---|---|---|
+| `main.rs` | `app.rs` (the router builder), tokio | handler/business logic |
+| `app.rs` | `routes::*`, tower layers, `AppState` | request-specific logic |
+| `routes/<domain>.rs` (handlers) | `AppState`, extractors, services, `AppError` | another domain's privates, raw response bodies |
+| `error.rs` (`AppError`) | domain error types | handlers, route wiring |
+
+Handlers are thin async fns returning `Result<T, AppError>` — they parse via an
+extractor, call one service method, and return the value (Axum serializes). The
+business logic survives a transport swap because nothing below the handler imports
+an Axum type.
+
+## Handlers (thin) & routing
+
+- A handler signature is `async fn(State<Arc<AppState>>, <Extractor>) -> Result<Json<T>, AppError>`.
+  Parse/validate via the extractor → call ONE service method → return `Ok(Json(..))`.
+- Never hand-build the response envelope or `match` on errors to build JSON —
+  `?`-propagate into `AppError` and let its `IntoResponse` shape the body.
+- Routes are assembled in `app.rs` (`Router::new().route(...).with_state(state)`);
+  one module per domain under `routes/`, re-exported through `routes/mod.rs`.
+
+## Error handling (the one shaper)
+
+- ONE `AppError` enum in `error.rs` implements `IntoResponse` — it is the ONLY
+  place that writes an error body (RFC 9457 problem shape per
+  `docs/api-contracts/error-format.md`). Map domain errors into it with
+  `thiserror` + `From` so handlers stay `?`-only.
+- Unknown/internal errors → 500 with a generic body; full detail goes to the
+  `tracing` logger only — never a `Debug`/backtrace or DB message to the client.
+
+## `?` over `.unwrap()` / `.expect()`
+
+- Request paths NEVER `.unwrap()` / `.expect()` — convert with `?` into `AppError`.
+  A panic in a handler aborts the task and leaks nothing useful to the client.
+- `.unwrap()`/`.expect()` is allowed ONLY at startup (binding the listener, reading
+  required config) where a failure SHOULD abort the process before serving traffic.
+
+## Extractors, state & middleware
+
+- Input validation is fail-closed at the extractor boundary: `Json<Dto>` /
+  `Query<Dto>` reject malformed input (400) before the handler body runs; a handler
+  never reads the raw request.
+- Shared state is `Arc<AppState>` injected via `State<Arc<AppState>>` — no global
+  mutable statics, no `lazy_static!` request state.
+- Tower middleware (`TraceLayer`, timeout, CORS, auth) lives in `app.rs` as
+  `.layer(...)` on the router — never inside an individual handler.
+
+## Testing
+
+- `#[tokio::test]` driving the router via `tower::ServiceExt::oneshot(request)` —
+  no real port is bound. One happy + one error path per route minimum.
+- Services: pure unit tests with fakes, no router. Assert the `AppError` variant on
+  the error path, not just the status, so a remap is caught.
+- `cargo clippy -- -D warnings` is the lint gate; warnings are errors.