litclaude-ai 0.2.2

package/plugins/litclaude/skills/programming/references/python/textual-tui.md

@@ -0,0 +1,201 @@
+# Textual TUI
+
+Textual builds rich, mouse-aware, scrollable, mobile-style TUIs on top of `rich`. Replaces curses, urwid, blessed.
+
+## Install
+
+```bash
+uv add textual
+uv add --dev textual-dev   # textual console + run --dev for hot reload
+```
+
+## Minimal app
+
+```python
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer, Button, Label
+from textual.containers import Vertical
+
+
+class CounterApp(App[None]):
+    """A trivial counter app."""
+
+    BINDINGS = [("q", "quit", "Quit")]
+    CSS = """
+    #count {
+        height: 3;
+        content-align: center middle;
+        background: $boost;
+    }
+    """
+
+    count: int = 0
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical():
+            yield Label("0", id="count")
+            yield Button("Increment", id="inc", variant="primary")
+            yield Button("Reset", id="reset", variant="warning")
+        yield Footer()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "inc":
+            self.count += 1
+        elif event.button.id == "reset":
+            self.count = 0
+        self.query_one("#count", Label).update(str(self.count))
+
+
+if __name__ == "__main__":
+    CounterApp().run()
+```
+
+Run:
+
+```bash
+uv run python counter.py
+```
+
+For hot reload during development:
+
+```bash
+uv run textual run --dev counter.py
+```
+
+## Reactive attributes
+
+Textual's `reactive()` descriptor turns a class attribute into something that watches assignments and re-renders automatically. Replaces the manual `query_one` + `update` dance.
+
+```python
+from textual.app import App, ComposeResult
+from textual.reactive import reactive
+from textual.widgets import Label
+
+
+class CountWidget(Label):
+    count: reactive[int] = reactive(0)
+
+    def render(self) -> str:
+        return f"Count: {self.count}"
+
+
+class CounterApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield CountWidget()
+
+    def on_key(self, event) -> None:
+        if event.key == "space":
+            self.query_one(CountWidget).count += 1
+```
+
+`reactive()` triggers `render()` (or `watch_<attr>` and `validate_<attr>` callbacks if defined). Use `recompose=True` if you need to call `compose()` again on change.
+
+## Async work — workers
+
+NEVER block the event loop. For network/disk/CPU work, use `@work` (creates a worker) or `run_worker`.
+
+```python
+import httpx
+from textual.app import App, ComposeResult
+from textual.widgets import Input, Static
+from textual.work import work
+
+
+class FetchApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Input(placeholder="URL", id="url")
+        yield Static(id="result")
+
+    @work(exclusive=True)
+    async def fetch(self, url: str) -> None:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get(url)
+        self.query_one("#result", Static).update(f"{response.status_code} - {len(response.text)} bytes")
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        self.fetch(event.value)
+```
+
+`exclusive=True` cancels the previous worker if the user submits a new URL before the first finishes. Workers integrate with Textual's lifecycle - they're cancelled when the app exits.
+
+`@work` is asyncio-flavoured under the hood. That is fine - it does not violate the no-asyncio rule because you are calling Textual's API, not importing asyncio yourself. Inside the worker body, use `httpx.AsyncClient` and other anyio-friendly libraries.
+
+## Action handlers
+
+Bind keys to method calls via `BINDINGS` and `action_*` methods.
+
+```python
+class App(App):
+    BINDINGS = [
+        ("ctrl+s", "save", "Save"),
+        ("ctrl+r", "reload", "Reload"),
+    ]
+
+    def action_save(self) -> None:
+        # Called on ctrl+s
+        ...
+
+    def action_reload(self) -> None:
+        ...
+```
+
+Bindings can also include the `priority=True` flag to fire before children get a chance.
+
+## CSS
+
+Textual's CSS supports selectors, variables (`$primary`, `$boost`), animations. Inline via `CSS = "..."` or external via `CSS_PATH = "app.tcss"`.
+
+```css
+Screen {
+    background: $surface;
+    color: $text;
+    layout: vertical;
+}
+
+#sidebar {
+    width: 30;
+    background: $boost;
+}
+
+Button.danger {
+    background: $error;
+}
+```
+
+Reload with `r` in dev mode (`textual run --dev`).
+
+## Testing
+
+```python
+import pytest
+from myapp import CounterApp
+
+
+@pytest.mark.anyio
+async def test_counter_increments() -> None:
+    app = CounterApp()
+    async with app.run_test() as pilot:
+        await pilot.click("#inc")
+        await pilot.click("#inc")
+        assert app.count == 2
+```
+
+`pilot.click(selector)`, `pilot.press("q")`, `pilot.pause()` for waiting on the next frame.
+
+## When NOT to use Textual
+
+| Need | Use |
+|---|---|
+| One-off CLI with structured output | typer + rich |
+| Progress bar in a script | rich.progress |
+| Tabular display of query results | rich.table |
+| Full-screen app with state, input, mouse | Textual |
+
+A pretty CLI is not a TUI. Reach for Textual when the user expects to navigate a UI, not when you want colours.
+
+## Sources
+
+- Textual docs: <https://textual.textualize.io>
+- Textual tutorial: <https://textual.textualize.io/tutorial/>
+- API reference: <https://textual.textualize.io/api/>

package/plugins/litclaude/skills/programming/references/python/type-patterns.md

@@ -0,0 +1,176 @@
+# Type Patterns
+
+How to use Python's type system to catch bugs at check time, not runtime.
+
+---
+
+## NewType — distinct primitives
+
+Same runtime type, different meaning. The type checker prevents mixing.
+
+```python
+from typing import NewType
+
+UserId = NewType("UserId", int)
+MovieId = NewType("MovieId", int)
+Email = NewType("Email", str)
+Seconds = NewType("Seconds", float)
+Milliseconds = NewType("Milliseconds", float)
+
+def get_user(user_id: UserId) -> User: ...
+def get_movie(movie_id: MovieId) -> Movie: ...
+def sleep(duration: Seconds) -> None: ...
+
+uid = UserId(42)
+mid = MovieId(42)
+
+get_user(uid)   # OK
+get_user(mid)   # type error: MovieId is not UserId
+get_user(42)    # type error: int is not UserId
+sleep(Milliseconds(100.0))  # type error
+```
+
+**Use when**: IDs, indices, keys, units of measurement — any pair where swapping is a bug.
+**Skip when**: ephemeral local math where branding adds noise with zero safety gain.
+
+---
+
+## Final — constants are const
+
+Module-level constants declare their intent. Reassignment is a type error.
+
+```python
+from typing import Final
+
+MAX_RETRIES: Final = 3
+API_BASE_URL: Final = "https://api.example.com"
+DEFAULT_TIMEOUT: Final = 30.0
+
+MAX_RETRIES = 5  # type error: cannot assign to Final
+```
+
+If it changes at runtime, it's not a constant — make it a function parameter or config field.
+
+---
+
+## TypeAlias — name complex types
+
+If a union or generic appears more than once, give it a name.
+
+```python
+# Python 3.12+
+type JsonValue = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+type Headers = dict[str, str]
+type Middleware = Callable[[Request], Awaitable[Response]]
+
+# Pre-3.12
+from typing import TypeAlias
+
+JsonValue: TypeAlias = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+```
+
+---
+
+## StrEnum / IntEnum — closed sets
+
+Any fixed set of known values. No string literals scattered through code.
+
+```python
+from enum import StrEnum, IntEnum, unique
+
+@unique
+class Role(StrEnum):
+    ADMIN = "admin"
+    USER = "user"
+    GUEST = "guest"
+
+@unique
+class HttpStatus(IntEnum):
+    OK = 200
+    NOT_FOUND = 404
+    INTERNAL_ERROR = 500
+
+# BAD
+def check_role(role: str) -> bool: ...
+
+# GOOD
+def check_role(role: Role) -> bool: ...
+```
+
+`StrEnum` when values serialize as strings (API, DB). `IntEnum` for numeric codes. Plain `Enum` for pure labels.
+
+---
+
+## Type narrowing — let the checker follow your logic
+
+`isinstance`, `is None`, and `match` narrow types automatically. Use them instead of `cast`.
+
+```python
+def process(value: str | int | None) -> str:
+    if value is None:
+        return "nothing"
+    # checker knows: str | int
+
+    if isinstance(value, str):
+        return value.upper()
+    # checker knows: int
+
+    return str(value * 2)
+```
+
+### TypeGuard for custom narrowing
+
+```python
+from typing import TypeGuard
+
+def is_valid_email(value: str) -> TypeGuard[Email]:
+    return "@" in value and "." in value.split("@")[1]
+
+def send(addr: str) -> None:
+    if not is_valid_email(addr):
+        raise ValueError(addr)
+    # checker knows: addr is Email
+    deliver(addr)
+```
+
+### TypeIs (Python 3.13+) — the strict version
+
+`TypeIs` is stricter than `TypeGuard` — it narrows in both `if` and `else` branches.
+
+```python
+from typing import TypeIs
+
+def is_str(value: str | int) -> TypeIs[str]:
+    return isinstance(value, str)
+
+def handle(v: str | int) -> None:
+    if is_str(v):
+        print(v.upper())   # checker knows: str
+    else:
+        print(v + 1)       # checker knows: int
+```
+
+---
+
+## Union syntax
+
+Always `X | Y`. Never `Union[X, Y]` or `Optional[X]`.
+
+```python
+# BAD
+from typing import Union, Optional
+def f(x: Optional[int]) -> Union[str, int]: ...
+
+# GOOD
+def f(x: int | None) -> str | int: ...
+```
+
+---
+
+## Sources
+
+- Python docs: [typing — NewType](https://docs.python.org/3/library/typing.html#newtype)
+- Python docs: [typing — Final](https://docs.python.org/3/library/typing.html#typing.Final)
+- Python docs: [typing — TypeGuard](https://docs.python.org/3/library/typing.html#typing.TypeGuard)
+- PEP 604: [Union syntax X | Y](https://peps.python.org/pep-0604/)
+- PEP 742: [TypeIs](https://peps.python.org/pep-0742/)

package/plugins/litclaude/skills/programming/references/rust/README.md

@@ -0,0 +1,317 @@
+# Rust Programmer
+
+Production Rust in 2026. **Explicit allocation, compile-time proof, zero hidden cost.** Type-state-first, unsafe-banished-by-default, agent-proof.
+
+## Identity — What Kind of Rust You Write
+
+You write Rust that looks like a Zig programmer designed it and a Rust compiler enforces it. Every allocation is visible. Every cost is explicit. Every invariant is encoded in the type system. Every cleanup is deterministic. The borrow checker, lifetime analysis, trait bounds, and `miri` then guarantee what Zig leaves to discipline.
+
+**Five pillars, every file, no exceptions:**
+
+| Pillar | Default Behavior | Reference |
+|---|---|---|
+| **Explicit allocation** | Arena for hot paths, `&[T]`/`Cow` over `Vec`/`String` in signatures, `try_*` when allocation can fail | [zero-cost-safety.md §1](zero-cost-safety.md) |
+| **Compile-time proof** | `const fn` everything const-eligible, `const { assert!(...) }` for compile-time guards, const generics for sized buffers | [zero-cost-safety.md §2](zero-cost-safety.md) |
+| **Zero hidden cost** | Slice-based APIs where caller owns memory, no hidden `.clone()`/`.to_string()`, `Cow` to defer allocation | [zero-cost-safety.md §3](zero-cost-safety.md) |
+| **Type-encoded invariants** | Newtype wrappers for every semantic unit, type-state for state machines, branded IDs | [type-state.md](type-state.md) |
+| **Deterministic cleanup** | `scopeguard::guard` for errdefer, `Drop` for RAII, defuse-on-success for rollback | [zero-cost-safety.md §5](zero-cost-safety.md) |
+
+The two highest-leverage tools Rust gives a coding agent:
+
+1. **Bounded polymorphism** (traits). Real, machine-checked, composable constraints.
+2. **Newtype-as-coordinate-space.** `Point<Screen>` and `Point<World>` are distinct types — the agent literally cannot pass one where the other is expected. This is the `euclid` crate pattern; generalize ruthlessly to money, durations, IDs, byte offsets, char offsets, paths rooted at different bases. Full patterns → [type-state.md](type-state.md).
+
+---
+
+## Hard Rules (Every `.rs` File)
+
+### 1. No `unwrap()`, No `expect()` Outside Tests
+
+```rust
+// WRONG
+let val = map.get("key").unwrap();
+
+// RIGHT — propagate or provide context
+let val = map.get("key").context("missing 'key' in config")?;
+```
+
+Typed errors for libraries ([thiserror](https://docs.rs/thiserror)), ad-hoc errors for binaries ([anyhow](https://docs.rs/anyhow) / [color-eyre](https://docs.rs/color-eyre)). Full stack → [libraries.md](libraries.md).
+
+### 2. No `unsafe` Without Miri Proof
+
+If `unsafe` is unavoidable, you have miri. Run it. Always. **Load [`../rust-ub/README.md`](../rust-ub/README.md) plus every file under [`../rust-ub/`](../rust-ub/)** for the full UB taxonomy, Miri escalation protocol (4 strictness levels), and the fix-and-prove workflow. Every `unsafe` block needs the three components from [unsafe-discipline.md](unsafe-discipline.md): safe wrapper, `// SAFETY:` comment, miri test.
+
+```bash
+cargo +nightly miri nextest run
+```
+
+### 3. Explicit Allocation — Arena by Default in Hot Paths
+
+**Do not scatter `Box::new()` / `Vec::new()` across hot loops.** Use arena allocation to make allocation scope visible and bulk-freeable. Full recipes → [zero-cost-safety.md §1](zero-cost-safety.md).
+
+```rust
+use bumpalo::Bump;
+
+fn parse_frame<'a>(arena: &'a Bump, raw: &[u8]) -> Frame<'a> {
+    let header = arena.alloc(parse_header(raw));
+    let payload = arena.alloc_slice_copy(&raw[HEADER_LEN..]);
+    Frame { header, payload }
+}
+// Caller owns arena. Caller decides when memory dies. Zero individual frees.
+```
+
+When arena is overkill (simple CLI, one-shot allocation), `Vec`/`String` are fine — but **function signatures still prefer borrows**:
+
+```rust
+// WRONG — forces caller to allocate
+fn process(input: String) -> String { ... }
+
+// RIGHT — caller chooses allocation strategy
+fn process(input: &str) -> Cow<'_, str> { ... }
+
+// BEST for hot paths — zero allocation, caller provides buffer
+fn process(input: &[u8], output: &mut [u8]) -> usize { ... }
+```
+
+### 4. Compile-Time First — const fn Everything Const-Eligible
+
+If a function CAN be `const fn`, it MUST be `const fn`. Full recipes → [zero-cost-safety.md §2](zero-cost-safety.md).
+
+```rust
+// Lookup tables computed at compile time — zero runtime cost
+const CRC_TABLE: [u32; 256] = {
+    let mut table = [0u32; 256];
+    let mut i = 0;
+    while i < 256 {
+        let mut crc = i as u32;
+        let mut j = 0;
+        while j < 8 {
+            crc = if crc & 1 != 0 { (crc >> 1) ^ 0xEDB88320 } else { crc >> 1 };
+            j += 1;
+        }
+        table[i] = crc;
+        i += 1;
+    }
+    table
+};
+
+// Compile-time assertions — catch violations at build time, not runtime
+const { assert!(std::mem::size_of::<Header>() == 12, "Header must be 12 bytes") };
+```
+
+Use `const generics` for stack-allocated buffers with compile-time size:
+
+```rust
+struct RingBuffer<T, const N: usize> {
+    data: [MaybeUninit<T>; N],
+    head: usize,
+    len: usize,
+}
+```
+
+### 5. Scope Guards — Deterministic Cleanup on Every Path
+
+Zig's `errdefer` in Rust. Full recipes → [zero-cost-safety.md §5](zero-cost-safety.md).
+
+```rust
+use scopeguard::guard;
+
+fn deploy(artifact: &Path) -> Result<(), DeployError> {
+    let backup = snapshot_current()?;
+    // errdefer: restore on failure
+    let rollback = guard(backup, |b| { let _ = restore(&b); });
+
+    upload(artifact)?;
+    health_check()?;
+
+    // Success: defuse the guard
+    scopeguard::ScopeGuard::into_inner(rollback);
+    Ok(())
+}
+```
+
+### 6. Bit-Level Layout — zerocopy for Wire Formats
+
+Never hand-write `transmute` or pointer casts for parsing binary data. Full recipes → [zero-cost-safety.md §4](zero-cost-safety.md).
+
+```rust
+use zerocopy::{FromBytes, IntoBytes, KnownLayout, Immutable};
+
+#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
+#[repr(C)]
+struct PacketHeader {
+    magic: [u8; 4],
+    version: u8,
+    flags: u8,
+    length: [u8; 2], // use byte array for packed fields, decode via from_le_bytes
+}
+```
+
+### 7. Exhaustive Match — No Wildcard on Enums You Control
+
+```rust
+// WRONG — silently ignores new variants
+match status {
+    Status::Ok => handle_ok(),
+    _ => handle_error(),
+}
+
+// RIGHT — compiler forces update when variants change
+match status {
+    Status::Ok => handle_ok(),
+    Status::NotFound => handle_not_found(),
+    Status::Timeout => handle_timeout(),
+}
+```
+
+For `#[non_exhaustive]` enums from external crates, the wildcard `_` is required — but add a `tracing::warn!` in the catch-all so you notice when new variants appear.
+
+### 8. Type-State Over Runtime Checks
+
+Never `if self.state == State::Validated`. Encode states as distinct types so the compiler refuses invalid transitions. Full patterns → [type-state.md](type-state.md).
+
+```rust
+struct Order<S: OrderState> { data: OrderData, _state: PhantomData<S> }
+struct Draft;
+struct Validated;
+struct Paid;
+
+impl Order<Draft> {
+    fn validate(self) -> Result<Order<Validated>, ValidationError> { ... }
+}
+impl Order<Validated> {
+    fn pay(self, payment: Payment) -> Result<Order<Paid>, PaymentError> { ... }
+}
+// Order<Draft> has no .pay() method. Compiler enforces the workflow.
+```
+
+---
+
+## Standard Library Defaults
+
+Full decision tree with rationale and code snippets → [libraries.md](libraries.md).
+
+| Category | Crate | Why |
+|---|---|---|
+| Async runtime | `tokio` | Ecosystem standard. Patterns → [async-tokio.md](async-tokio.md) |
+| HTTP server | `axum` + `tower` | Type-safe extractors, tower middleware. Stack → [axum-stack.md](axum-stack.md) |
+| CLI | `clap` derive + `color-eyre` | Typed args, beautiful errors. Stack → [clap-stack.md](clap-stack.md) |
+| Serialization | `serde` + `serde_json` | Non-negotiable for any boundary type |
+| Error (library) | `thiserror` | Derive `Error` with zero boilerplate |
+| Error (binary) | `anyhow` / `color-eyre` | Context-rich ad-hoc errors |
+| Database | `sqlx` (compile-time checked) | No runtime SQL surprises |
+| Arena alloc | `bumpalo` / `typed-arena` | Explicit allocation scope. Patterns → [zero-cost-safety.md §1](zero-cost-safety.md) |
+| Zero-copy parse | `zerocopy` | Safe binary parsing, no transmute. Patterns → [zero-cost-safety.md §4](zero-cost-safety.md) |
+| Scope guard | `scopeguard` | errdefer/defer. Patterns → [zero-cost-safety.md §5](zero-cost-safety.md) |
+| Stack collections | `smallvec` / `arrayvec` / `tinyvec` | Stack-first, heap-spillover. Patterns → [zero-cost-safety.md §3](zero-cost-safety.md) |
+| Bitfield | `bitfield` / `modular-bitfield` | Bit-packed flags. Patterns → [zero-cost-safety.md §4](zero-cost-safety.md) |
+| Testing | `proptest` + `insta` | Property + snapshot tests. Patterns → [proptest-insta.md](proptest-insta.md) |
+| Concurrency | `tokio::sync` / `parking_lot` | Channel-first, lock-second. Patterns → [concurrency.md](concurrency.md) |
+
+---
+
+## Cargo Strict Configuration
+
+Every new project gets the strict lint config from [cargo-strict.md](cargo-strict.md). The non-negotiable CI gate:
+
+```bash
+cargo fmt --all -- --check && \
+cargo clippy --all-targets --all-features -- -D warnings && \
+cargo nextest run && \
+cargo +nightly miri nextest run  # when unsafe is involved
+```
+
+---
+
+## Code Review Checklist (Post-Write, Every PR)
+
+Run through this list after writing any Rust code. Every item links to its recipe.
+
+| # | Check | Fix Reference |
+|---|---|---|
+| 1 | Every function signature prefers `&[T]`/`&str`/`Cow` over owned types | [zero-cost-safety.md §3](zero-cost-safety.md) |
+| 2 | Hot-path allocations use arena (`bumpalo`) not scattered `Box`/`Vec` | [zero-cost-safety.md §1](zero-cost-safety.md) |
+| 3 | Const-eligible functions are `const fn` | [zero-cost-safety.md §2](zero-cost-safety.md) |
+| 4 | Lookup tables / config constants computed at compile time | [zero-cost-safety.md §2](zero-cost-safety.md) |
+| 5 | Binary format parsing uses `zerocopy`, not `transmute` | [zero-cost-safety.md §4](zero-cost-safety.md) |
+| 6 | Cleanup logic uses `scopeguard` or `Drop`, never manual `if err` cleanup | [zero-cost-safety.md §5](zero-cost-safety.md) |
+| 7 | Distinct semantic units are newtypes, not primitive aliases | [type-state.md](type-state.md) |
+| 8 | State machines use type-state, not runtime `if state ==` | [type-state.md](type-state.md) |
+| 9 | No `unwrap()`/`expect()` outside `#[cfg(test)]` | [libraries.md](libraries.md) |
+| 10 | Every `unsafe` has SAFETY comment + miri test | [unsafe-discipline.md](unsafe-discipline.md), [../rust-ub/](../rust-ub/) |
+| 11 | Match on owned enums is exhaustive (no `_ =>`) | This file §7 |
+| 12 | Clippy pedantic passes with zero warnings | [cargo-strict.md](cargo-strict.md) |
+| 13 | Property tests exist for any function with a nontrivial domain | [proptest-insta.md](proptest-insta.md) |
+| 14 | Concurrency uses channels first, locks second, atomics last | [concurrency.md](concurrency.md) |
+| 15 | Async code uses `JoinSet` for structured concurrency | [async-tokio.md](async-tokio.md) |
+
+---
+
+## Default Cargo.toml Dependencies — Zero-Cost Safety Stack
+
+Every new project starts with these alongside the standard deps from [cargo-strict.md](cargo-strict.md):
+
+```toml
+# Zero-cost safety stack
+bumpalo = { version = "3", features = ["collections"] }
+scopeguard = "1"
+smallvec = { version = "1", features = ["union", "const_generics"] }
+zerocopy = { version = "0.8", features = ["derive"] }
+
+# Add when needed:
+# typed-arena = "2"           # homogeneous arena
+# arrayvec = "0.7"            # fixed-capacity stack vec
+# tinyvec = { version = "1", features = ["alloc"] }
+# bitfield = "0.17"           # bit-packed flags
+# modular-bitfield = "0.11"   # richer bitfield API
+# bytemuck = { version = "1", features = ["derive"] }
+```
+
+---
+
+## Reference Index
+
+| File | When to Load |
+|---|---|
+| [zero-cost-safety.md](zero-cost-safety.md) | Arena, allocator, const fn, comptime, zero-alloc, bitfield, repr, scopeguard, errdefer, Zig-like patterns |
+| [type-state.md](type-state.md) | Newtype wrappers, type-state machines, branded IDs, phantom types |
+| [unsafe-discipline.md](unsafe-discipline.md) | Any `unsafe` block — SAFETY comments, safe wrappers, miri proof |
+| [libraries.md](libraries.md) | Library selection, crate decision tree, dependency audit |
+| [cargo-strict.md](cargo-strict.md) | Project bootstrap, lint config, CI gate commands |
+| [async-tokio.md](async-tokio.md) | Async runtime, spawning, cancellation, `JoinSet`, `select!` |
+| [axum-stack.md](axum-stack.md) | HTTP services — axum + sqlx + tower + tracing |
+| [clap-stack.md](clap-stack.md) | CLI tools — clap derive + color-eyre + indicatif |
+| [concurrency.md](concurrency.md) | Locks, atomics, channels, loom model checker |
+| [proptest-insta.md](proptest-insta.md) | Property tests, snapshot tests, round-trip invariants |
+| [one-liners.md](one-liners.md) | `rust-script` one-liners, disposable scripts, inline deps |
+| [../rust-ub/README.md](../rust-ub/README.md) | UB hunting — miri escalation, sanitizers, fuzzing |
+| [../rust-ub/ub-taxonomy.md](../rust-ub/ub-taxonomy.md) | 14-category UB taxonomy with detection status |
+| [../rust-ub/miri-sanitizers-loom.md](../rust-ub/miri-sanitizers-loom.md) | Miri flags, ASAN/TSAN/MSAN, loom, cargo-fuzz |
+
+---
+
+## The Shape of Every Function
+
+```rust
+/// One-line doc explaining WHAT, not HOW.
+///
+/// # Errors
+/// Returns `FooError::Bar` when the input is invalid.
+const fn frobnicate<'a>(
+    arena: &'a Bump,        // explicit allocator when arena is in play
+    input: &[u8],           // borrow, not owned
+    output: &mut [u8],      // caller-provided buffer
+) -> Result<&'a Frob, FrobError> {
+    // ...
+}
+```
+
+**Why this shape:** the caller sees every cost. Allocation scope is the arena's lifetime. Input is borrowed. Output buffer is caller-owned. Error is typed. The compiler enforces all of it.
+
+---
+
+## Activation
+
+This skill activates whenever you are writing or modifying any `.rs` file or `Cargo.toml`. One-off scripts get the strict treatment too — `rust-script` + the same lints, the same gates. Details → [one-liners.md](one-liners.md).
+
+**The promise:** production hygiene with throwaway ergonomics. Explicit allocation, compile-time proof, zero hidden cost, and **agent-proof safety at any volume**.