chore(knowledge): group concepts into domain subfolders

.agents/skills/process-issues/SKILL.md

@@ -43,8 +43,8 @@ For each qualifying issue (ordered by issue number), achieve ALL of these before
 
 - Minimal, focused changes
 - Positive and negative tests pass
-- Security tests added if change touches parser, interpreter, VFS, network, git, or user input (per `knowledge/security-testing.md`)
-- Threat model updated if new attack surface (per `knowledge/threat-model.md`)
+- Security tests added if change touches parser, interpreter, VFS, network, git, or user input (per `knowledge/security/security-testing.md`)
+- Threat model updated if new attack surface (per `knowledge/security/threat-model.md`)
 
 ### 4. Ship via `/ship`
 

.agents/skills/ship/SKILL.md

@@ -33,7 +33,7 @@ Review the changes on this branch (use `git diff origin/main...HEAD` and `git lo
 3. **Write missing tests** for any uncovered code paths:
    - **Positive tests**: happy path, valid inputs, expected state transitions
    - **Negative tests**: invalid inputs, error conditions, boundary cases, permission failures, missing resources
-   - **Security tests**: if change touches parser, interpreter, VFS, network, git, or user input — add tests per `knowledge/security-testing.md`
+   - **Security tests**: if change touches parser, interpreter, VFS, network, git, or user input — add tests per `knowledge/security/security-testing.md`
    - **Compatibility tests**: if change affects Bash behavior parity — add differential tests comparing against real Bash
 4. **Run all tests** to confirm green: `just test`
 5. If any test fails, fix the code or test until green
@@ -43,9 +43,9 @@ Review the changes on this branch (use `git diff origin/main...HEAD` and `git lo
 Review the changes and update project artifacts where applicable. Skip items that aren't affected.
 
 1. **Knowledge** (`knowledge/`): if the change affects durable behavior, decisions, constraints, threats, tests, or operations, update the relevant OKF knowledge in the same change
-2. **Threat model** (`knowledge/threat-model.md`): if the change introduces new attack surfaces, external inputs, authentication/authorization changes, or data handling — add or update threat entries using the `TM-<CATEGORY>-<NNN>` format and add `// THREAT[TM-XXX-NNN]` code comments at mitigation points
+2. **Threat model** (`knowledge/security/threat-model.md`): if the change introduces new attack surfaces, external inputs, authentication/authorization changes, or data handling — add or update threat entries using the `TM-<CATEGORY>-<NNN>` format and add `// THREAT[TM-XXX-NNN]` code comments at mitigation points
 3. **AGENTS.md**: if the change adds new knowledge, commands, or modifies development workflows — update the relevant section
-4. **Limitations** (`knowledge/limitations.md`): if a limitation was added or lifted, update the table; if builtins changed, run `just regen-builtins` and commit the JSON
+4. **Limitations** (`knowledge/operations/limitations.md`): if a limitation was added or lifted, update the table; if builtins changed, run `just regen-builtins` and commit the JSON
 5. **Documentation** (`crates/bashkit/docs/`): if the change affects public APIs, tools, or features — update the relevant guide markdown files
 
 ### Phase 3b: Code Simplification
@@ -66,12 +66,12 @@ Analyze all changed code for security vulnerabilities:
 
 1. **Input validation** — check that user-supplied data (script input, file paths, environment variables, command arguments) is validated before use
 2. **Injection risks** — look for command injection, path traversal, environment variable injection, or shell metacharacter issues
-3. **Sandbox escapes** — if changes touch VFS, builtins, or process execution, verify they cannot escape the sandbox (see `knowledge/threat-model.md`)
+3. **Sandbox escapes** — if changes touch VFS, builtins, or process execution, verify they cannot escape the sandbox (see `knowledge/security/threat-model.md`)
 4. **Resource exhaustion** — check for unbounded loops, unbounded allocations, or missing limits on user-controlled sizes
 5. **Error handling** — ensure errors don't leak internal state, file paths, or sensitive information
 6. **Unsafe code** — review any `unsafe` blocks for soundness; prefer safe alternatives
 
-If security issues are found, fix them, add regression tests, and update `knowledge/threat-model.md` if a new threat category is identified.
+If security issues are found, fix them, add regression tests, and update `knowledge/security/threat-model.md` if a new threat category is identified.
 
 ### Phase 3d: Design Quality Review
 

.claude/commands/maintain.md

@@ -1,4 +1,4 @@
-Run the pre-release maintenance checklist from `knowledge/maintenance.md`. Find and fix all issues before reporting.
+Run the pre-release maintenance checklist from `knowledge/operations/maintenance.md`. Find and fix all issues before reporting.
 
 ## Arguments
 
@@ -28,7 +28,7 @@ Key tools: `cargo update`, `cargo outdated`, `cargo audit`, `cargo deny check`,
 
 Ensure the threat model covers all features, security tests exist for all mitigated threats, and no OWASP-style issues exist in the codebase.
 
-Key references: `knowledge/threat-model.md`, `knowledge/security-testing.md`, `crates/bashkit/docs/threat-model.md`
+Key references: `knowledge/security/threat-model.md`, `knowledge/security/security-testing.md`, `crates/bashkit/docs/threat-model.md`
 
 ### 3. Tests are comprehensive and green
 
@@ -94,7 +94,7 @@ Key tools:
 - `gh run list --workflow=fuzz.yml --limit 7` (fuzz)
 - `gh api repos/OWNER/REPO/actions/runs/RUN_ID/jobs` (inspect failed jobs)
 
-If failures persist >2 days, escalate per `knowledge/maintenance.md`.
+If failures persist >2 days, escalate per `knowledge/operations/maintenance.md`.
 If the agent cannot fix a failure, it MUST open a GitHub issue and report the
 pass as blocked — never silently skip.
 
@@ -108,6 +108,6 @@ pass as blocked — never silently skip.
 
 ## Notes
 
-- This is a goal-based checklist. The spec (`knowledge/maintenance.md`) defines *what* must be true. This skill defines *how* to verify and fix.
+- This is a goal-based checklist. The spec (`knowledge/operations/maintenance.md`) defines *what* must be true. This skill defines *how* to verify and fix.
 - Use parallel agents for independent sections when possible.
 - For scoped runs, still verify that fixes don't break other areas (`just test` at minimum).

.github/workflows/apidocs-drift.yml

@@ -5,7 +5,7 @@ name: API Reference Drift
 # site/src/content/apidocs/*.md and feeds the /api/{python,typescript} pages;
 # the node-only site build just renders it, so it must be regenerated and
 # committed on release — fix drift by running `just apidocs` and committing.
-# See knowledge/documentation.md ("API reference hosting").
+# See knowledge/operations/documentation.md ("API reference hosting").
 #
 # Per AGENTS.md commit-attribution rules this workflow never auto-commits; it
 # only fails so a human regenerates and commits under a real identity.

.github/workflows/ci.yml

@@ -84,7 +84,7 @@ jobs:
     # Build the browser package (@everruns/bashkit-wasm) and run its headless
     # integration tests, proving the single-threaded bundle loads with no
     # COOP/COEP headers and that sync + async execution both work. See
-    # knowledge/browser-package.md. Keep wasm-bindgen-cli in lockstep with the
+    # knowledge/runtimes/browser-package.md. Keep wasm-bindgen-cli in lockstep with the
     # wasm-bindgen version in Cargo.lock.
     name: WASM web package
     runs-on: ubuntu-latest

.github/workflows/coreutils-args-drift.yml

@@ -2,7 +2,7 @@ name: Coreutils Args Drift
 
 # Detects upstream uutils/coreutils argument-surface AND vendored-module
 # drift, and proposes both as a single PR. See
-# knowledge/coreutils-args-port.md for the design (args mode + module mode).
+# knowledge/runtimes/coreutils-args-port.md for the design (args mode + module mode).
 #
 # Module set is read from `crates/bashkit-coreutils-port/vendored.toml`;
 # adding a vendored module is one TOML stanza there and the drift run
@@ -324,7 +324,7 @@ jobs:
           correctly per \`AGENTS.md\`. Intermediate bot commits in this PR
           are discarded by squash.
 
-          Design: [\`knowledge/coreutils-args-port.md\`](../tree/main/knowledge/coreutils-args-port.md).
+          Design: [\`knowledge/runtimes/coreutils-args-port.md\`](../tree/main/knowledge/runtimes/coreutils-args-port.md).
           EOF
 
           if gh pr view "$branch" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then

.github/workflows/publish-python.yml

@@ -21,7 +21,7 @@ env:
   CARGO_TERM_COLOR: always
   # abi3 (stable ABI): one interpreter builds a single cp39-abi3 wheel per
   # platform that runs on Python 3.9+. No per-minor-version matrix. See
-  # knowledge/python-package.md § abi3.
+  # knowledge/runtimes/python-package.md § abi3.
   BUILD_PYTHON: "3.12"
 
 jobs:
@@ -119,22 +119,22 @@ jobs:
   # Reduced-feature Pyodide/Emscripten wheel (browser / JupyterLite).
   # Separate job: distinct toolchain (nightly Rust + emsdk + pyodide-build) and a
   # single Python version dictated by the pyodide-build ABI lockstep.
-  # See knowledge/emscripten-wheels.md.
+  # See knowledge/runtimes/emscripten-wheels.md.
   build-emscripten:
     name: Build wheel - emscripten (Pyodide)
     runs-on: ubuntu-latest
     env:
       # Keep in lockstep with the `wasm` job in python.yml: the nightly's LLVM,
       # pyodide-build's Emscripten/binaryen, and Pyodide's EH ABI must agree.
-      # See knowledge/emscripten-wheels.md "version triangle". Bump together.
+      # See knowledge/runtimes/emscripten-wheels.md "version triangle". Bump together.
       RUST_NIGHTLY: "nightly-2026-05-29"
       PYODIDE_BUILD_VERSION: "0.34.4"
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # Python 3.13 -> pyodide-build's modern config (Pyodide 0.29.x, Emscripten
       # 4.0.9), whose binaryen understands modern LLVM's wasm target-features and
-      # whose runtime supports wasm exception handling. See knowledge/emscripten-wheels.md.
+      # whose runtime supports wasm exception handling. See knowledge/runtimes/emscripten-wheels.md.
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"

.github/workflows/python.yml

@@ -193,14 +193,14 @@ jobs:
           retention-days: 5
 
   # Build the reduced-feature Pyodide/Emscripten wheel and smoke-test it in a
-  # Pyodide venv. See knowledge/emscripten-wheels.md for the feature matrix and the
+  # Pyodide venv. See knowledge/runtimes/emscripten-wheels.md for the feature matrix and the
   # pyodide-build <-> Emscripten <-> Python <-> Rust version lockstep.
   wasm:
     name: Build wheel (Pyodide/Emscripten)
     runs-on: ubuntu-latest
     env:
       # Pinned for reproducibility: this trio must stay aligned on the wasm
-      # feature set + exception-handling ABI (see knowledge/emscripten-wheels.md
+      # feature set + exception-handling ABI (see knowledge/runtimes/emscripten-wheels.md
       # "version triangle"). pyodide-build 0.34.x (under Python 3.13) selects
       # Pyodide 0.29.x / Emscripten 4.0.9; the nightly's LLVM must match that
       # binaryen. Bump all three together and re-verify the wheel imports.
@@ -220,7 +220,7 @@ jobs:
       # must satisfy our deps' MSRV (monty needs rustc 1.95) and edition 2024,
       # so it has to be recent; its LLVM (19+) matches Emscripten 4.0.9's
       # binaryen, which is what avoids the wasm-opt target-feature skew that
-      # older Emscripten (3.1.x) hit. See knowledge/emscripten-wheels.md.
+      # older Emscripten (3.1.x) hit. See knowledge/runtimes/emscripten-wheels.md.
       - name: Install nightly Rust with the Emscripten target
         # @nightly matches the repo's other nightly jobs (fuzz.yml, nightly.yml,
         # ci.yml); the exact nightly is pinned via the toolchain: input below.

AGENTS.md

@@ -24,41 +24,41 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn
 | Knowledge | Description |
 |------|-------------|
 | knowledge-contract | Knowledge maintenance rules + OKF v0.2 conformance rules |
-| architecture | Core interpreter architecture, module structure |
-| parser | Bash syntax parser design |
-| vfs | Virtual filesystem abstraction |
-| testing | Testing strategy and patterns |
-| builtins | Builtin command design (trait, ShellRef, ExecutionPlan) |
-| security-testing | Fail-point injection for security testing |
-| threat-model | Security threats and mitigations |
-| parallel-execution | Threading model, Arc usage |
-| documentation | Rustdoc guides, embedded markdown |
-| release-process | Version tagging, crates.io + PyPI + npm publishing |
-| limitations | Negative spec: intentional gaps (L-* IDs), partial features, POSIX stance |
-| tool-contract | Public LLM Tool trait contract |
-| git-support | Sandboxed git operations on VFS |
-| python-builtin | Embedded Python via Monty, security, resource limits |
-| eval | LLM eval study on the mira framework, dataset format, scoring |
-| maintenance | Pre-release maintenance requirements |
-| python-package | Python package, PyPI wheels, platform matrix |
-| scripted-tool-orchestration | Compose ToolDef+callback pairs into OrchestratorTool via bash scripts |
-| ssh-support | Sandboxed SSH/SCP/SFTP operations |
-| zapcode-runtime | Embedded TypeScript via ZapCode, VFS bridging, resource limits |
-| request-signing | Transparent Ed25519 request signing (bot-auth) per RFC 9421 |
-| interactive-shell | Interactive REPL mode with rustyline line editing |
-| sqlite-builtin | Embedded SQLite via Turso (MemoryIO + VfsIO backends, dot-commands) |
-| coreutils-args-port | Codegen port of uutils clap definitions + uucore modules |
-| credential-injection | Per-host HTTP credential injection without exposing secrets |
-| http-transport | Pluggable HTTP transport: route curl/wget via host egress boundary |
-| performance-results | Benchmark/eval result locations and `/benches` site aggregation contract |
-| emscripten-wheels | Reduced-feature Pyodide/Emscripten Python wheel |
-| browser-package | Slim single-threaded wasm package (`@everruns/bashkit-wasm`) for browsers + JS runtimes, no COOP/COEP |
+| foundations/architecture | Core interpreter architecture, module structure |
+| foundations/parser | Bash syntax parser design |
+| foundations/vfs | Virtual filesystem abstraction |
+| operations/testing | Testing strategy and patterns |
+| foundations/builtins | Builtin command design (trait, ShellRef, ExecutionPlan) |
+| security/security-testing | Fail-point injection for security testing |
+| security/threat-model | Security threats and mitigations |
+| foundations/parallel-execution | Threading model, Arc usage |
+| operations/documentation | Rustdoc guides, embedded markdown |
+| operations/release-process | Version tagging, crates.io + PyPI + npm publishing |
+| operations/limitations | Negative spec: intentional gaps (L-* IDs), partial features, POSIX stance |
+| integrations/tool-contract | Public LLM Tool trait contract |
+| integrations/git-support | Sandboxed git operations on VFS |
+| runtimes/python-builtin | Embedded Python via Monty, security, resource limits |
+| operations/eval | LLM eval study on the mira framework, dataset format, scoring |
+| operations/maintenance | Pre-release maintenance requirements |
+| runtimes/python-package | Python package, PyPI wheels, platform matrix |
+| integrations/scripted-tool-orchestration | Compose ToolDef+callback pairs into OrchestratorTool via bash scripts |
+| integrations/ssh-support | Sandboxed SSH/SCP/SFTP operations |
+| runtimes/zapcode-runtime | Embedded TypeScript via ZapCode, VFS bridging, resource limits |
+| security/request-signing | Transparent Ed25519 request signing (bot-auth) per RFC 9421 |
+| integrations/interactive-shell | Interactive REPL mode with rustyline line editing |
+| runtimes/sqlite-builtin | Embedded SQLite via Turso (MemoryIO + VfsIO backends, dot-commands) |
+| runtimes/coreutils-args-port | Codegen port of uutils clap definitions + uucore modules |
+| security/credential-injection | Per-host HTTP credential injection without exposing secrets |
+| security/http-transport | Pluggable HTTP transport: route curl/wget via host egress boundary |
+| operations/performance-results | Benchmark/eval result locations and `/benches` site aggregation contract |
+| runtimes/emscripten-wheels | Reduced-feature Pyodide/Emscripten Python wheel |
+| runtimes/browser-package | Slim single-threaded wasm package (`@everruns/bashkit-wasm`) for browsers + JS runtimes, no COOP/COEP |
 
 ### Documentation
 
 - **Public docs** live in `docs/` — user-facing articles (security, guides, etc.)
 - **Rustdoc guides** live in `crates/bashkit/docs/` as markdown files
-- Rustdoc guides embedded via `include_str!` (see `knowledge/documentation.md`)
+- Rustdoc guides embedded via `include_str!` (see `knowledge/operations/documentation.md`)
 - Edit `crates/bashkit/docs/*.md`, not the doc modules in `lib.rs`
 - Add "See also" cross-links when creating new guides
 - Run `cargo doc --open` to preview rustdoc changes
@@ -131,7 +131,7 @@ and are aggregated by `crates/bashkit/tests/integration/main.rs` into a single b
 New behavioral tests go there. A small number of files stay as top-level
 `tests/*.rs` because they need their own binary (process-global env
 mutation, `--test-threads=1`, ssh-only feature isolation) — the list and
-criteria live in `knowledge/testing.md`.
+criteria live in `knowledge/operations/testing.md`.
 
 ### Rust
 
@@ -143,7 +143,7 @@ criteria live in `knowledge/testing.md`.
 
 ### Stderr from builtins must not leak internal Debug shapes
 
-**TM-INF-022** in `knowledge/threat-model.md`. No `{:?}`/`{:#?}` in
+**TM-INF-022** in `knowledge/security/threat-model.md`. No `{:?}`/`{:#?}` in
 `crates/bashkit/src/builtins/`; use `Display` or a domain formatter
 (reference: `format_compile_errors` in `builtins/jq/errors.rs`); cap
 diagnostics ≤ 1 KB; test-only Debug needs `// debug-ok: <reason>`.
@@ -185,14 +185,14 @@ Do not mix criterion `.md` files into `crates/bashkit-bench/results/`.
 3. `cargo clippy --all-targets --all-features -- -D warnings`
 4. `just test` (feature-sliced; never `cargo test --all-features` in one invocation — see Local Dev)
 5. Unit tests cover both positive (expected behavior) and negative (error handling, edge cases) scenarios
-6. Security tests if change touches user input, parsing, sandboxing, or permissions (see `knowledge/security-testing.md`)
+6. Security tests if change touches user input, parsing, sandboxing, or permissions (see `knowledge/security/security-testing.md`)
 7. Compatibility/differential tests if change affects Bash behavior parity (compare against real Bash)
 8. Rebase on main: `git fetch origin main && git rebase origin/main` (for worktrees: verify the worktree `HEAD` is on latest `origin/main` before editing)
 9. Update knowledge if behavior or durable project facts change
 10. CI green before merge
 11. Resolve all PR comments
-12. `cargo bench --bench parallel_execution` if touching Arc/async/Interpreter/builtins (see `knowledge/parallel-execution.md`)
-13. `just bench-sqlite` if touching the sqlite builtin or its VFS/IO bridge (see `knowledge/sqlite-builtin.md`)
+12. `cargo bench --bench parallel_execution` if touching Arc/async/Interpreter/builtins (see `knowledge/foundations/parallel-execution.md`)
+13. `just bench-sqlite` if touching the sqlite builtin or its VFS/IO bridge (see `knowledge/runtimes/sqlite-builtin.md`)
 14. `just bench` if changes might impact performance (interpreter, builtins, tools)
 15. `ruff check crates/bashkit-python && ruff format --check crates/bashkit-python` if touching Python code
 

CHANGELOG.md

@@ -122,7 +122,7 @@
   addresses, and the response size cap, and returns typed errors
   (`Denied`/`Timeout`/`TooLarge`/`Transport`) that map onto curl exit codes
   (7/28/63/1). Mirrors fetchkit's transport injection so one host egress
-  implementation can back both libraries. See `knowledge/http-transport.md`
+  implementation can back both libraries. See `knowledge/security/http-transport.md`
   ([#2147](https://github.com/everruns/bashkit/pull/2147)).
 - **`xargs -P` parallel execution** — `-P/--max-procs` runs command batches
   concurrently, with `--process-slot-var` exposing the slot index to each child