gilesknap

Ansible playbook structure, tags, topology rules, branch switching, and operational foot-guns for the K3s cluster.

ArgoCD operations on the K3s cluster — branch repointing via ansible, OCI Helm chart wiring foot-guns (oci:// prefix breaks chart-name resolution), and the InvalidSpecError cache bounce.

Architecture decisions and historical reversals for this repo's bwrap-based Claude sandbox. Covers real claude off PATH, container-scoped PATs, Ubuntu-24.04 CI bwrap workarounds, dogfood ≈ guest, the `just promote` three-layer model (no JSONC editing), and two walked-back paths (Python orchestration; embedding in python-copier-template). Surface before edits to `.devcontainer/claude-sandbox/{claude-shadow,install.sh,promote.sh}`, `install`, `tests/`, `.github/workflows/ci.yml`, or `.claude/commands/verify-sandbox.md`; or before any suggestion to re-introduce Python tooling, embed in python-copier-template, persist gh/glab PATs across containers, or auto-edit JSONC devcontainer.json.

Cloudflare Tunnel and Access configuration for exposing K3s services externally.

OAuth2-proxy authentication setup, configuration, and troubleshooting for the K3s cluster.

RKLLama (RK3588 NPU LLM server) operations — pod CLI quirks, model layout, hardware pinning, and the silent-failure modes of `rkllama_client pull`.

Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.

Sealing, rotating, and troubleshooting SealedSecrets in the K3s cluster — file naming rules, placeholder base64 pitfalls, seal-argocd-dex subcommands, pod restart requirements after reseal.

How to run and extend this repo's acceptance test suite. Use when adding or modifying tests, verifying a change end-to-end, or when ./run_all.sh fails. Covers the oracle contract, the offline test harness (serve a local inventory + the myst build --all export oracle), and how to add a new acceptance test.

The load-bearing mystmd v1.10.1 facts and design invariants that keep this project's API cross-references case-sensitive (re.match ≠ re.Match). READ THIS BEFORE modifying anything under src/ (the plugin, inventory writer, {py} role, {apidoc} directive), python/ (extractor), or any objects.inv / anchor logic. Warns about the $-anchor lowercasing foot-gun and the other collapse traps that silently break case-sensitivity.

Bootstrap the Node/mystmd + Python (griffe/sphinx/sphobjinv) toolchain for this repo. Use when npm/npx/myst/python are missing, when builds or tests fail with "command not found", or when setting up a fresh dev container. Covers the read-only-rootfs and zsh-no-rc gotchas specific to the sandbox this project was built in.

How to test and verify changes to thoth — the tox GATE, the injected-fakes testing model (and why green CI does not prove a boundary change works), the live-smoke marker, and how to deploy a branch to the live VPS appliance and verify it before merge (the gold standard: git checkout + uv sync + systemd restart, plus the deploy-to-verify gotchas). Use when running the test suite, adding tests, deciding whether a change is safe to merge, or deploying / testing / verifying a branch on the VPS (the live appliance / production box) — e.g. "test this on the vps", "deploy the branch to the appliance", "verify live before merge", "restart thoth-slack". Also covers packaging/publishing the container image + OCI Helm chart (Charts/thoth, _helm.yml, the helm-schema hook foot-guns, verifying a ghcr publish is public) — e.g. "test the chart publish", "tag a beta", "why does the helm-schema lint hook fail".

Engineering and process conventions for working on thoth that aren't obvious from the code — how to shape LLM output, the clean-slate stance, and how findings turn into issues and docs. Use when implementing a feature, changing LLM-facing prompts, or deciding how to record work.

Orientation map for the thoth codebase — what to read first, what each module does, the vault page-type model, and the Hindsight semantic-index reality. Use when starting work on thoth and you need to know where things live or which file owns a responsibility, before diving into a feature or bug.

Work through a pull request's review comments systematically: fan out read-only subagents to analyse each comment in parallel, group coupled findings, then apply fixes serially with one commit per logical fix and a reply + thread-resolve for each. Works for any reviewer — automated bots (CodeRabbit, Copilot, etc.) or humans. Use when a PR has many outstanding review comments to triage and address, when the user says "walk through the review comments", "address the PR comments", or "clear the review on PR #N".

Network egress, firewall, and lateral-movement design for this repo's bwrap Claude sandbox. The per-process egress jail (netns + pasta routing allowlist, ADR 0015, issue #56) is ON by default as of 2026-06-18, fail-closed, with a CLAUDE_SANDBOX_EGRESS_JAIL=0 escape hatch — overriding ADR 0005's earlier open-egress default. Surface BEFORE proposing or discussing ANY network change: egress filtering, firewall / nftables / iptables / DOCKER-USER, `--unshare-net`, netns / veth, pasta / slirp4netns, a CONNECT or SNI proxy, `HTTPS_PROXY` injection, VLAN / segmentation, Claude Code's native sandbox `allowedDomains`, or device-access networking (EPICS / Channel Access / pvAccess / PMAC).

Guidelines for writing and maintaining project documentation.

YAML & JSON Schema Conventions