diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9ea17df
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+This repo documents a reproducible CachyOS + GNOME workstation. README.md is the entry point; `docs/00-15` carry phase detail; `scripts/` carry automation.
+
+## Skill routing
+
+When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.
+
+Key routing rules:
+- Product ideas/brainstorming → invoke /office-hours
+- Strategy/scope → invoke /plan-ceo-review
+- Architecture → invoke /plan-eng-review
+- Design system/plan review → invoke /design-consultation or /plan-design-review
+- Full review pipeline → invoke /autoplan
+- Bugs/errors → invoke /investigate
+- QA/testing site behavior → invoke /qa or /qa-only
+- Code review/diff check → invoke /review
+- Visual polish → invoke /design-review
+- Ship/deploy/PR → invoke /ship or /land-and-deploy
+- Save progress → invoke /context-save
+- Resume context → invoke /context-restore
+- Author a backlog-ready spec/issue → invoke /spec
+- Sync docs after shipping → invoke /document-release
+- Generate missing docs → invoke /document-generate
+
+## Repo rules
+
+- Review each phase before running on another machine; not a one-click installer.
+- Never commit secrets, tokens, keys, `.env` with values, Tailscale keys, browser profiles.
+- Prefer official repos over AUR; upstream installers for fast-moving AI tools.
+- `scripts/verify.sh` must pass (clean-login PATH probe + `pacman -Qq` parity).
+- Jev gate (`jev-gate --request`) before mass/deletes/deploys/schema edits.
diff --git a/README.md b/README.md
index 092ba93..2ae7f8d 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ media tools and everyday productivity — documented, scripted and verifiable.
-
+
@@ -23,7 +23,7 @@ media tools and everyday productivity — documented, scripted and verifiable.
-
+
@@ -35,7 +35,7 @@ media tools and everyday productivity — documented, scripted and verifiable.
-Verified against GNOME Shell 50.4 on Wayland · last audit 2026-09-11
+Verified against GNOME Shell 50.5 on Wayland · last audit 2026-10-02
@@ -69,7 +69,7 @@ It is designed around:
- Kooha (+ OBS Studio optional) + KTorrent
- Obsidian
- Thunderbird
-- Telegram Desktop
+- Telegram Desktop (`telegram-desktop` package; binary name differs — verify with `pacman -Ql`)
- SSHFS
- Modern CLIs: bat, eza, btop, fastfetch, duf, ripgrep, fd, fzf, delta, lazygit, zoxide, go-yq
- Terminal workflow: neovim, tmux, mosh (for Tailscale SSH sessions)
@@ -144,6 +144,7 @@ Do **not** commit:
```text
cachyos-dev-workstation/
├── README.md
+├── CLAUDE.md
├── LICENSE
├── .gitignore
├── docs/
@@ -224,8 +225,8 @@ CachyOS provides multiple desktop environments through its current installer, in
## Clone this repository
```bash
-git clone https://github.com/RavenRepo/cachyossystem.git
-cd cachyossystem
+git clone https://github.com/RavenRepo/cachyos-dev-workstation.git
+cd cachyos-dev-workstation
```
## Run the phases
@@ -898,11 +899,14 @@ herdr integration install hermes
Only install integrations you actually use.
-Observed on this workstation (2026-09): `claude` 2.1.268, `codex` 0.153.4,
-`kiro-cli` 2.21.2, `pi` 0.85.1, `herdr` 0.9.0 (all `~/.local/bin` via
-upstream installers), `opencode` 1.18.29 (pacman), `omp` 18.1.17
-(`~/.bun/bin/omp` via Bun), plus `hermes`/`hermes-acp`/`hermes-agent`.
-npm global: `oh-my-claude-sisyphus`. Agent state (`~/.claude/`,
+Observed on this workstation (2026-10-02): `claude` 2.1.287, `codex` 0.159.3,
+`kiro-cli` 2.21.2, `pi` 0.87.1, `herdr` 0.9.3 (all `~/.local/bin` via
+upstream installers), `opencode` v2.0.11 (`~/.opencode/bin` via upstream
+installer), `omp` 18.4.4
+(`~/.bun/bin/omp` via Bun), plus `hermes`/`hermes-acp`/`hermes-agent` v0.21.1,
+`antigravity` (IDE v2.13.0, `~/.local/bin`), `agent-memory`, `jev-gate`.
+npm global: `oh-my-claude-sisyphus`, `neon`, `llm-checker`. Bun global:
+`@oh-my-pi/pi-coding-agent`. Agent state (`~/.claude/`,
`~/.codex/config.toml`) stays out of Git. Details: `docs/05-ai-tooling.md`.
---
@@ -1488,12 +1492,14 @@ must be rotated, not merely deleted. Full procedure in `docs/09-security.md`.
Recommended workspace:
```text
-~/Projects/
+~/Projects/ # active work (observed 2026-09-19: anatomy, ladder, stuntkit, ...)
├── personal/
├── work/
├── experiments/
├── open-source/
└── archived/
+/mnt/kronos/Projects/ # bulk archive (129 entries observed 2026-09-19)
+/mnt/kronos/jev/ # Jev risk gate (canonical, not a project workspace)
```
Example:
@@ -1502,6 +1508,10 @@ Example:
mkdir -p ~/Projects/{personal,work,experiments,open-source,archived}
```
+Keep `~/` root clean: `~/main`, `~/src/theming`, `~/postiz`, `~/twenty`,
+`~/researchdoc`, stray `~/package.json` / `~/node_modules` belong under
+`~/Projects/` or `/mnt/kronos/Projects/`.
+
A typical project:
```text
diff --git a/docs/03-gnome.md b/docs/03-gnome.md
index 1dd68a0..7792cf4 100644
--- a/docs/03-gnome.md
+++ b/docs/03-gnome.md
@@ -1,6 +1,6 @@
# 03 — GNOME
-Target: **GNOME Shell 50.4 on Wayland** (CachyOS, verified 2026-09-11).
+Target: **GNOME Shell 50.5 on Wayland** (CachyOS, verified 2026-09-19).
The GNOME version matters more than usual here — see
[Version constraints](#version-constraints).
@@ -17,12 +17,16 @@ sudo pacman -S --needed \
nautilus \
file-roller \
xdg-user-dirs \
- gnome-extensions-app
+ extension-manager
```
+`gnome-extensions-app` is not a package on current CachyOS/GNOME releases — the
+`gnome-extensions` CLI ships inside `gnome-shell` itself, and the actual GUI
+manager is `extension-manager` (referenced below).
+
## Current appearance
-Applied state on this workstation (2026-09-11):
+Applied state on this workstation (2026-09-19):
| Layer | Value | Source |
|---|---|---|
@@ -233,9 +237,9 @@ Any such theme must be regenerated after each GNOME major upgrade.
## Version constraints
-Checked against the extensions.gnome.org API on 2026-09-11:
+Checked against the extensions.gnome.org API on 2026-09-19:
-| Extension | Max shell version | Usable on 50.4 |
+| Extension | Max shell version | Usable on 50.5 |
|---|---|---|
| Blur my Shell | 50 (v72) | yes |
| Rounded Window Corners Reborn | 50 (v25) | yes |
@@ -277,7 +281,7 @@ with Extension Manager (`extension-manager`), which installs from
extensions.gnome.org. Do not install extensions or themes from arbitrary
gnome-look.org tarballs.
-Enabled on this workstation:
+Enabled on this workstation (observed 2026-10-02):
```text
dash-to-dock@micxgx.gmail.com
@@ -288,8 +292,14 @@ gsconnect@andyholmes.github.io
CoverflowAltTab@palatis.blogspot.com
tilingshell@ferrarodomenico.com
just-perfection-desktop@just-perfection
+auto-move-windows@gnome-shell-extensions.gcampax.github.com
+places-menu@gnome-shell-extensions.gcampax.github.com
```
+`auto-move-windows` and `places-menu` are bundled with `gnome-shell` itself
+(not installed separately) and got enabled since the last audit; keep them
+only if they're actually in use, otherwise disable to keep the set minimal.
+
Installed but not active: `dash-in-panel@fthx`.
`user-theme` is retained even though no shell theme is set — it is the
diff --git a/docs/04-development.md b/docs/04-development.md
index f0f250b..e756432 100644
--- a/docs/04-development.md
+++ b/docs/04-development.md
@@ -6,8 +6,8 @@
sudo pacman -S --needed nodejs npm
```
-The repository `nodejs` package tracks the current release (v26 at time of
-writing), which is **not** an LTS version. Do not fight pacman over this — use
+The repository `nodejs` package tracks the current release (v26.8.2 observed
+2026-09-19), which is **not** an LTS version. Do not fight pacman over this — use
`mise` for per-project versions:
```bash
@@ -66,6 +66,8 @@ sudo -u postgres initdb -D /var/lib/postgres/data
sudo systemctl enable --now postgresql
```
+Observed 2026-09-19: `psql` 18.6, service `enabled` + `active`.
+
## Podman
```bash
diff --git a/docs/05-ai-tooling.md b/docs/05-ai-tooling.md
index a735dbc..7224160 100644
--- a/docs/05-ai-tooling.md
+++ b/docs/05-ai-tooling.md
@@ -2,20 +2,22 @@
AI installers change frequently. Prefer official upstream installation instructions.
-Observed on this workstation (2026-09):
+Observed on this workstation (2026-10-02):
| Tool | Version | Install source |
|---|---|---|
-| `claude` | 2.1.268 | upstream installer → `~/.local/bin` |
-| `codex` | 0.153.4 | upstream installer → `~/.local/bin` |
+| `claude` | 2.1.287 | upstream installer → `~/.local/bin` |
+| `codex` | 0.159.3 | upstream installer → `~/.local/bin` |
| `kiro-cli` | 2.21.2 | upstream installer → `~/.local/bin` |
-| `pi` | 0.85.1 | upstream installer → `~/.local/bin` |
-| `herdr` | 0.9.0 | upstream installer → `~/.local/bin` |
-| `hermes`, `hermes-acp`, `hermes-agent` | — | alongside the herdr integrations |
-| `opencode` | 1.18.29 | pacman (`opencode`) |
-| `omp` | 18.1.17 | bun (`~/.bun/bin/omp`) |
+| `pi` | 0.87.1 | upstream installer → `~/.local/bin` |
+| `herdr` | 0.9.3 | upstream installer → `~/.local/bin` |
+| `hermes`, `hermes-acp`, `hermes-agent` | v0.21.1 | alongside the herdr integrations |
+| `opencode` | v2.0.11 | upstream installer → `~/.opencode/bin` (PATH addition required) |
+| `omp` | 18.4.4 | bun (`~/.bun/bin/omp`) |
+| `antigravity` | IDE v2.13.0 | upstream installer → `~/.local/bin` |
+| `agent-memory`, `jev-gate` | — | `~/.local/bin` (Neon memory / Jev risk gate) |
-npm global: `oh-my-claude-sisyphus`.
+npm global: `oh-my-claude-sisyphus`, `neon`, `llm-checker`. Bun global: `@oh-my-pi/pi-coding-agent`.
## Claude Code
@@ -35,7 +37,8 @@ curl -fsSL https://cli.kiro.dev/install | bash
curl -fsSL https://opencode.ai/install | bash
```
-or from the Arch repositories:
+Upstream installs to `~/.opencode/bin` (requires PATH addition, see
+`docs/14-shell.md`). Also available from Arch repos:
```bash
sudo pacman -S --needed opencode
@@ -74,8 +77,31 @@ MCP and agent state live outside Git (names only, never commit contents):
~/.claude/
~/.claude.json
~/.codex/config.toml
+~/.config/opencode/
+~/.opencode/
+~/.hermes/
+~/.gemini/
+~/.kiro/
```
+## Skills (2026-09-19)
+
+`~/.claude/skills` carries ~70 entries: the gstack suite, 8 Neon skills
+(`neon`, `neon-ai-gateway`, `neon-auth`, `neon-functions`,
+`neon-object-storage`, `neon-postgres`, `neon-postgres-branches`,
+`neon-postgres-egress-optimizer`, pinned in `~/skills-lock.json`), plus
+`orca-cli` / `orchestration`. VS Code carries `anthropic.claude-code`.
+Keep skill credentials out of Git.
+
+## Antigravity / Hermes / Jev gate
+
+- Antigravity IDE (`antigravity`, v2.13.0) lives in `~/.local/bin`.
+- Hermes Agent (`hermes-agent` v0.21.1) is installed via git to
+ `~/.hermes/hermes-agent`.
+- `jev-gate` (`~/.local/bin`, canonical `/mnt/kronos/jev`) fronts risky
+ actions: exit 0 = proceed, exit 3 = escalate. Never print or store
+ `TYPESAFE_API_KEY`; source `/mnt/kronos/jev/.env` silently.
+
## Security
Never commit agent credentials, MCP tokens, provider keys, or personal prompt/configuration data containing secrets.
diff --git a/docs/06-browsers-editors.md b/docs/06-browsers-editors.md
index e7067b9..97b27ff 100644
--- a/docs/06-browsers-editors.md
+++ b/docs/06-browsers-editors.md
@@ -8,7 +8,8 @@ Zed (package `zed`, binary `zeditor`):
sudo pacman -S --needed zed
```
-VS Code is optional and is **not** installed on this workstation.
+VS Code is installed from the repos on this workstation (`code` 1.138.0,
+extension `anthropic.claude-code`):
Choose one source if you want it:
```bash
diff --git a/docs/07-databases-containers.md b/docs/07-databases-containers.md
index 78950fd..759fc74 100644
--- a/docs/07-databases-containers.md
+++ b/docs/07-databases-containers.md
@@ -2,7 +2,8 @@
## PostgreSQL
-Keep the database local by default.
+Keep the database local by default. Observed 2026-09-19: 18.6,
+`postgresql.service` enabled + active.
```bash
systemctl status postgresql --no-pager
diff --git a/docs/08-networking.md b/docs/08-networking.md
index 52fb9ee..ff4196e 100644
--- a/docs/08-networking.md
+++ b/docs/08-networking.md
@@ -16,6 +16,9 @@ tailscale ip
tailscale netcheck
```
+Observed 2026-09-19: `tailscale` 1.102.4, 4-node tailnet (this host + goku
+reachable, 2 offline).
+
## Tailscale SSH
If intentionally used:
@@ -50,6 +53,9 @@ sudo systemctl enable --now caddy
sudo ss -lntp | grep caddy # confirm the bind address, not just "it works"
```
+Observed 2026-09-19: `caddy` v2.11.4 installed, service `disabled` +
+`inactive` (on-demand only).
+
A reverse proxy on `0.0.0.0:80` with no authentication in front of a
development application is the single easiest way to expose this workstation.
`README.md` §26 lists the preconditions; treat them as blocking, not advisory.
diff --git a/docs/09-security.md b/docs/09-security.md
index cfb0ff9..978ae4f 100644
--- a/docs/09-security.md
+++ b/docs/09-security.md
@@ -129,6 +129,22 @@ file, or a Git object as compromised and rotate it. Removing the line does not
un-leak it: it stays in `~/.bash_history`, in shell session logs, and in Git
history if it was ever committed.
+On 2026-09-19 `scripts/verify.sh` failed again on an inline
+`export _API_KEY=` in `~/.zshrc` plus a key-named file in
+`~/`. Same rule applies: rotate, remove the line/file, clear history.
+
+### Jev risk gate (canonical `/mnt/kronos/jev`)
+
+Before ambiguous, risky, destructive, or irreversible actions (deletes,
+deploys, merges, schema/prod writes, mass edits), run:
+
+```bash
+jev-gate --request ""
+```
+
+Exit 0 = proceed, exit 3 = escalate to user. Never print or store
+`TYPESAFE_API_KEY`; source `/mnt/kronos/jev/.env` silently.
+
## No AppArmor
This baseline intentionally does not install or configure AppArmor.
diff --git a/docs/10-productivity-media.md b/docs/10-productivity-media.md
index 2108255..b903041 100644
--- a/docs/10-productivity-media.md
+++ b/docs/10-productivity-media.md
@@ -20,10 +20,16 @@ Do not enable a kill switch until Tailscale and firewall routing are tested.
sudo pacman -S --needed obsidian thunderbird telegram-desktop
```
+Observed 2026-09-19: `obsidian`, `thunderbird` present; `telegram-desktop`
+7.2.8 installed but `command -v telegram-desktop` misses — list with
+`pacman -Ql telegram-desktop` to confirm the binary name.
+
## OBS / Kooha / KTorrent
```bash
sudo pacman -S --needed obs-studio kooha ktorrent
```
+Observed 2026-10-02: `kooha`, `ktorrent`, `obs-studio` (32.2.2) all present.
+
OBS should be the primary production recorder; Kooha is useful for quick captures.
diff --git a/docs/14-shell.md b/docs/14-shell.md
index 11ff7a4..1582dd0 100644
--- a/docs/14-shell.md
+++ b/docs/14-shell.md
@@ -94,9 +94,10 @@ produces only:
```
No `~/.local/bin` and no `~/.bun/bin`. Since `claude`, `codex`, `kiro-cli`,
-`pi`, and `herdr` all live in `~/.local/bin`, and `bun` and `omp` live in
-`~/.bun/bin`, running `chsh -s /usr/bin/zsh` without fixing PATH first removes
-the entire AI toolchain from the shell.
+`pi`, `herdr`, and `antigravity` all live in `~/.local/bin`, `bun` and `omp`
+live in `~/.bun/bin`, and `opencode` v2.x lives in `~/.opencode/bin`, running
+`chsh -s /usr/bin/zsh` without fixing PATH first removes the entire AI
+toolchain from the shell.
This is invisible if you test with `zsh -ic ...` from an existing fish session,
because the child process inherits the parent's PATH. Always test with a
@@ -116,9 +117,10 @@ export BUN_INSTALL="$HOME/.bun"
typeset -U path PATH # keep PATH deduplicated
path=(
- "$HOME/.local/bin" # claude, codex, kiro-cli, pi, herdr
+ "$HOME/.local/bin" # claude, codex, kiro-cli, pi, herdr, antigravity, jev-gate
"$HOME/.bun/bin" # bun, omp
"$HOME/.npm-global/bin" # npm global prefix
+ "$HOME/.opencode/bin" # opencode (upstream installer, v2.x)
$path
)
export PATH
@@ -146,7 +148,7 @@ Do not change the login shell first. Verify, then commit.
# 1. Patch ~/.zshrc with the PATH block above.
# 2. Prove a fresh login works — not an inherited one.
-for b in claude codex kiro-cli pi herdr bun omp; do
+for b in claude codex kiro-cli pi herdr antigravity jev-gate bun omp opencode; do
env -i HOME="$HOME" USER="$USER" TERM=xterm /usr/bin/zsh -ic "command -v $b"
done
diff --git a/scripts/03-ai-tools.sh b/scripts/03-ai-tools.sh
index 04c098b..cdab3e6 100755
--- a/scripts/03-ai-tools.sh
+++ b/scripts/03-ai-tools.sh
@@ -11,4 +11,6 @@ curl -fsSL https://herdr.dev/install.sh | sh
echo
echo "Codex/Pi/omp follow their official installers (here: ~/.local/bin, omp via Bun)."
+echo "opencode upstream lands in ~/.opencode/bin — add it to PATH (docs/14-shell.md)."
+echo "antigravity/hermes-agent/jev-gate/agent-memory follow their official installers to ~/.local/bin."
echo "opencode is also available via pacman; authenticate and configure everything interactively."
diff --git a/scripts/verify.sh b/scripts/verify.sh
index 0ba7158..9ef4d7a 100755
--- a/scripts/verify.sh
+++ b/scripts/verify.sh
@@ -168,6 +168,10 @@ resolve "pi" pi
resolve "herdr" herdr
resolve "opencode" opencode
resolve "omp" omp
+resolve "antigravity" antigravity --version
+resolve "hermes-agent" hermes-agent
+resolve "jev-gate" jev-gate
+resolve "agent-memory" agent-memory
c_head "GNOME extension consistency"
if command -v gsettings >/dev/null; then