aps-build-and-env

name

aps-build-and-env

description

Use when setting up this repo on a new or freshly wiped macOS machine, rebuilding the Python 한국어 트리거: 새 맥북 세팅, 환경 재구축, venv 재생성, 서브모듈 초기화, 심링크 복구, 헤드리스 인증, 부트스트랩. .venv, fixing broken external skill symlinks, re-running scripts/env_bootstrap.sh, restoring headless claude auth (setup-token / headless.env), initializing git submodules, recreating the isolated TTS/STT venvs, or registering a new machine in machine_registry.json. Korean triggers: 새 맥북 세팅, 환경 구축, 환경 재구축, venv 재생성, 서브모듈 초기화, 심링크 복구, 헤드리스 인증, 환경 패리티, 부트스트랩. English triggers: new machine setup, environment rebuild, bootstrap, env parity, venv rebuild, submodule init, headless auth, CLI install. Do NOT use for day-2 fleet operation, launchd lifecycle, or runner anatomy (use aps-run-and-operate); do NOT use for config axes like model policy, hooks wiring, or plists (use aps-config-and-flags); do NOT use for diagnosing why a job fails (use aps-debugging-playbook).

aps-build-and-env — Recreate the Working Environment from Scratch

Scope: everything needed to go from a blank macOS machine to a machine where this repo's agent harness (interactive Claude Code sessions + unmanned launchd fleet) runs. Day-2 operation (starting/stopping jobs, signal bus, outputs) is owned by aps-run-and-operate.

Definitions used throughout:

• Harness = the Claude Code operating layer of this repo: .claude/ (skills, rules, hooks) + scripts/ + the scheduled launchd fleet.
• Parity = the invariant that the home and office machines behave identically. git syncs tracked files; scripts/env_bootstrap.sh + env-parity.json sync the machine-external state (symlinks, venv, CLIs) that git cannot.
• launchd = macOS's scheduler daemon; all cron-style jobs here are launchd agents (plists in scripts/launchd/).

All commands assume cwd = repo root (~/thaki/ai-platform-strategy on existing machines).

---

0. Prerequisites (before cloning)

Item	How	Why
Xcode CLT	xcode-select --install	git, compilers
Homebrew	https://brew.sh installer	nearly every CLI below
SSH key registered with GitHub, with access to the ThakiCloud org	ssh -T [e-mail] must greet you	parent repo + most submodules are private SSH remotes
pyenv	brew install pyenv	provides the base interpreters (3.12.8 for the main venv, 3.11.x for VoxCPM2)
uv	brew install uv	the venv/package manager of record (.claude/rules/python-runtime.md)

The parent repo remote (as of 2026-07-06) is [e-mail]:sylvanus4/ai-strategy.git (private, personal remote — not under the ThakiCloud org).

---

1. Clone + submodule init

git clone [e-mail]:sylvanus4/ai-strategy.git ~/thaki/ai-platform-strategy
cd ~/thaki/ai-platform-strategy

Work on main only — no feature branches; sync at session start, push at end (see .claude/rules/git-workflow-main-only.md).

Submodule pins from .gitmodules (verified 2026-07-06). Mixed HTTPS/SSH remotes; all ThakiCloud repos are private (HTTPS ones need gh auth login or a credential helper; SSH ones need your org-authorized key). external/hermes-agent is public.

Submodule	Remote type	Branch pin	Note
ai-suite	https	dev	frontend monorepo
thaki-ui	https	develop	(not dev)
ai-platform-webui	https	dev	Go backend despite the name
thaki-cloud-assistant	https	main
praxis	ssh	main
thakicloud.github.io	ssh	(no pin — tracks remote HEAD)	blog
tkai-deploy	ssh	dev	GitOps
external/hermes-agent	https	main	public (NousResearch)
ml-platform	ssh	dev	⚠ code lives on dev; main is stale design docs
kubeflow-llm-training	ssh	main
tkai-multi-cluster	ssh	main

You do NOT need all of them. As of 2026-07-06 the reference machine leaves kubeflow-llm-training, tkai-deploy, and tkai-multi-cluster uninitialized (git submodule status shows a - prefix). Initialize what you need:

git submodule update --init ai-suite ai-platform-webui thakicloud.github.io praxis external/hermes-agent
# Everything: git submodule update --init   (add --remote to move to branch tips — see router rule first)
git submodule status        # '-' = uninitialized, '+' = checked out ≠ recorded SHA

Routing depth (which submodule for which question) is owned by .claude/rules/thaki-platform-repos.md — a router table; read it before diving into any submodule. Never edit submodule files from the parent repo.

---

2. Python: the single 3.12.8 venv

Canonical spec: .claude/rules/python-runtime.md (single unified interpreter; all repo scripts run via .venv/bin/python). Exact rebuild (same commands the rule and env_bootstrap.sh heal_venv() use):

pyenv install 3.12.8            # once per machine
cd ~/thaki/ai-platform-strategy
uv venv --python "$HOME/.pyenv/versions/3.12.8/bin/python3.12" --prompt ai-platform .venv
echo "3.12.8" > .python-version   # already tracked; should be a no-op
VIRTUAL_ENV="$PWD/.venv" uv pip install "headroom-ai[code,relevance]"
.venv/bin/python --version        # must print: Python 3.12.8

Notes:

• There is no requirements.txt; pyproject.toml + uv.lock exist but the core dependency documented for the venv is headroom-ai[code,relevance] — everything else is installed on demand per skill (this is by design).
• Install into this venv only via VIRTUAL_ENV="$PWD/.venv" uv pip install <pkg>. Do not create ad-hoc venvs inside the repo.
• Never rm -rf .venv — uv venv overwrites in place, so deletion is unnecessary (prohibited by the python-runtime rule; see traps table).

---

3. env_bootstrap: verify → heal

scripts/env_bootstrap.sh reconciles the machine-external state recorded in env-parity.json (committed at repo root):

bash scripts/env_bootstrap.sh --verify   # read-only drift report; exit 1 = heal needed
bash scripts/env_bootstrap.sh --heal     # fix what it can
bash scripts/env_bootstrap.sh --export   # (existing machine only) re-record current state

What each check covers (read from the script, 2026-07-06):

Check	verify	heal
External skill symlinks (.claude/skills/*, .claude/agents/* → repos outside this one, e.g. ~/academic-research-skills)	broken/missing detection	clones the source_repo at the recorded branch, recreates the symlink
.venv	exists + Python version matches manifest (3.12.8)	rebuilds via uv (same commands as §2) + installs headroom-ai
Required CLIs	reports missing (never auto-installs)	reports only — install manually per §4
gws under launchd PATH	resolvable with launchd's minimal PATH?	symlinks the real gws into ~/.local/bin/gws

env-parity.json fields: python.version, external_symlinks[] (link/target/source_repo/clone_path/branch), required_clis[]. --export regenerates it from the current machine and preserves manually filled source_repo hints; it skips the write when nothing changed (avoids daily no-op commits). Known open item: the webwright symlink entry carries a _note that its source_repo needs confirming — --heal will warn+skip it (status: open).

---

4. CLI inventory

Authoritative list = required_clis in env-parity.json: gh gws hf rtk uv rsync jq node python3 docker. Install hints:

CLI	Install	Post-install
gh	brew install gh	gh auth login
gws	npm i -g @googleworkspace/cli (hint from env_bootstrap.sh heal path)	authorize once interactively; then --heal for the launchd symlink
hf	pip install -U "huggingface_hub[cli]" [unverified exact install source — verify with: head -1 $(which hf)]	hf auth login if pushing
rtk	present at /opt/homebrew/bin/rtk (v0.34.1) [unverified install channel — verify with: brew list rtk]	optional; commands fall back to native if absent (.claude/rules/rtk-token-optimization.md)
uv	brew install uv	—
rsync, jq, node	rsync ships with macOS; brew install jq node	node also arrives via nvm on some machines
docker	Docker Desktop	only needed for container work
claude (not in the manifest but load-bearing)	official Claude Code installer → ~/.local/bin/claude	see §5 for headless auth

Re-check any time with bash scripts/env_bootstrap.sh --verify (CLI section reports missing ones).

---

5. Headless auth (unmanned claude -p runs)

Canonical spec: .claude/rules/scheduled-skill-model-escalation.md §"헤드리스 인증 전제" — headless runs must use the subscription OAuth token, never a metered API key.

1. In a real interactive terminal (NOT inside a Claude session — stdin must be a TTY):

   claude setup-token
   

2. Put the token in ~/.config/claude-code/headless.env (machine-local, OUTSIDE the repo), containing export CLAUDE_CODE_OAUTH_TOKEN=..., and lock it down:

   chmod 600 ~/.config/claude-code/headless.env
   

   (Verified on the reference machine: file exists, mode -rw-------.)
3. Verify:

   env -u ANTHROPIC_API_KEY claude -p "AUTH_OK" --model sonnet </dev/null
   # expected output: AUTH_OK
   

Every scheduled runner sources this file. The full hardening pattern additionally runs a defensive unset ANTHROPIC_API_KEY before invoking claude -p — but as of 2026-07-06 only 13 of 22 scripts/skills/run_*.sh runners carry the unset (verified: run_twitter_timeline.sh, run_blog_evolve.sh, others); 9 runners source headless.env WITHOUT it (run_bespin_news.sh, run_daily_pm.sh, run_gmail_spam_sweep.sh, run_hf_trending.sh, run_morning_surface.sh, run_sales_crm_morning.sh, run_skill_evolution.sh, run_sprint_archive.sh, run_selfharness_evolve.sh — enumerate with grep -L 'unset ANTHROPIC_API_KEY' scripts/skills/run_*.sh). This is an open hardening gap: those 9 are exposed to API-key poisoning if a stray ANTHROPIC_API_KEY ever enters their environment. When debugging auth on one of them, do NOT rule out key poisoning. NEVER add ANTHROPIC_API_KEY to .claude/settings.local.json env — it forces metered billing or 401s on all claude -p calls. This file works even when the login keychain is locked (launchd sessions).

---

6. Isolated media venvs (OPTIONAL — only if TTS/STT pipelines are needed)

These are deliberately separate from .venv (conflicting transformers pins). Never merge them. Canonical rules: .claude/rules/tts-generation.md, .claude/rules/stt-generation.md. All models auto-download to ~/.cache/huggingface on first run; brew install ffmpeg first.

Purpose	Interpreter / venv	Install (exact, from the driver scripts)
VoxCPM2 TTS (video narration, voice clone)	any pyenv 3.11.x (auto-detected by scripts/tts/voxcpm_tts.py; override VOXCPM_PYTHON)	~/.pyenv/versions/3.11.9/bin/python -m pip install voxcpm==2.0.3 soundfile (3.11.9 is the version present on the reference machine; the script also probes 3.11.12 and any 3.11.*)
Qwen3-ASR STT	~/.venvs/qwen-asr	python3 -m venv --system-site-packages ~/.venvs/qwen-asr && ~/.venvs/qwen-asr/bin/python -m pip install 'qwen-asr==0.0.6'
pyannote diarization	~/.venvs/pyannote	python3 -m venv --system-site-packages ~/.venvs/pyannote && ~/.venvs/pyannote/bin/python -m pip install 'pyannote.audio>=4.0' — gated HF models: accept licenses at hf.co/pyannote/speaker-diarization-community-1 and /speaker-diarization-3.1 with your HF_TOKEN account, or the pipeline 403s
Qwen3-TTS (audiobooks, multivoice)	~/.venvs/qwen3-tts	python3 -m venv --system-site-packages ~/.venvs/qwen3-tts && ~/.venvs/qwen3-tts/bin/python -m pip install qwen-tts==0.1.1

--system-site-packages is the trick that reuses the base interpreter's MPS-built torch instead of reinstalling multi-GB torch per venv. As of 2026-07-06 the reference machine has ~/.venvs/{qwen-asr,qwen3-tts} (plus unrelated mlx-vlm, paddleocr-vl) but NOT ~/.venvs/pyannote — install it only when diarization is actually needed.

Smoke tests:

python3 scripts/tts/voxcpm_tts.py --text "테스트입니다" --out /tmp/t.wav   # your cloned voice
bash scripts/stt/verify_stt.sh                                            # STT contract check

---

7. Machine registration + the daily parity loop

1. Register the new machine's Slack label in scripts/machine_registry.json (hostname with trailing .local stripped → label). Consumer: scripts/machine_label.py, used by scripts/slack_post_message.py to tag every post so home/office alerts are distinguishable. Current entries: Hanui-MacBookPro-4 (회사맥), Hanui-MacBookPro (home). Unknown hosts fall back to 🖥️ <hostname> — so this step is cosmetic-but-expected, not blocking.

   hostname   # strip .local, add to "machines" in scripts/machine_registry.json
   

2. The parity loop that keeps two machines converged (verified in the skill files):
   • sod-ship (start of day) runs bash scripts/env_bootstrap.sh --heal — pulls the other machine's manifest and heals local drift.
   • eod-ship Phase 1.8 (end of day) runs scripts/env_bootstrap.sh --export and commits the refreshed env-parity.json so the OTHER machine can heal tomorrow. Launchd installation of these jobs is day-2 territory → aps-run-and-operate.

---

8. Go backend — REFERENCE ONLY

• Real path: ai-platform-webui/ai-platform/backend/go/ (inside the submodule). The path ai-platform/backend/go/ cited in the root CLAUDE.md does not exist at repo root on this machine (verified 2026-07-06) — treat that CLAUDE.md path as stale.
• go.work is gitignored in both the parent repo (.gitignore:116) and the submodule (ai-platform-webui/.gitignore:102) — it is a per-developer artifact; absence after a fresh clone is normal.
• Do not develop platform code here. Product development happens in the submodule repos on their own branches with their own CLAUDE.md conventions (.claude/rules/thaki-platform-repos.md).

---

Known traps (each cost real time at least once)

Trap	Symptom	Fix / rule
launchd can't see npm globals	headless jobs fail to find gws (2026-06-19 sales-crm calendar miss)	env_bootstrap.sh --heal symlinks the real gws into ~/.local/bin (part of launchd's minimal PATH)
Keychain-locked launchd sessions	interactive-auth CLIs fail in scheduled jobs	headless.env token file (§5) works without keychain; prefer file-based tokens for anything scheduled
Deleting .venv	breaks the unified-interpreter invariant	never delete; uv venv overwrites in place (.claude/rules/python-runtime.md). The rule says the safety gate blocks rm -rf .venv; as of 2026-07-06 pre-tool-safety-gate.sh has no .venv-specific pattern — do not rely on the gate, just don't delete
gws stdout header pollution	Using keyring backend: keyring line breaks JSON parsing	redirect: gws ... --format json 2>/dev/null > /tmp/out.json then parse the file (.claude/rules/mcp-graceful-degradation.md)
Submodule main-vs-dev confusion	"ml-platform has no code"	ml-platform code is on dev; main is stale design docs. Also thaki-ui pins develop, not dev. Check .gitmodules branch=, not assumptions
ANTHROPIC_API_KEY anywhere in env for claude -p	401s or silent metered billing on the whole fleet	keep it out of .claude/settings.local.json; runners unset it defensively (§5)
Stale CLAUDE.md Go path	cd ai-platform/backend/go fails	real path is ai-platform-webui/ai-platform/backend/go/ (§8)
env-parity.json missing on an exotic checkout	--verify exits 1 immediately	it is committed at repo root; if truly absent run --export on a healthy machine first
pyproject.toml uv-workspace member ai-platform/backend/python doesn't exist at root	possible uv workspace warnings	candidate cleanup item (status: open); uv venv / uv pip install per §2 work regardless on the reference machine

---

Post-setup acceptance checklist

• git branch --show-current → main; git submodule status shows expected pins
• .venv/bin/python --version → Python 3.12.8
• bash scripts/env_bootstrap.sh --verify → exit 0 ("environment parity OK")
• env -u ANTHROPIC_API_KEY claude -p "AUTH_OK" --model sonnet </dev/null → AUTH_OK
• hostname entry present in scripts/machine_registry.json (or accepted fallback)
• (if media pipelines needed) VoxCPM2 smoke test produces a wav in your voice

---

When NOT to use this skill

You want to…	Use instead
Install/start/stop launchd jobs, understand runner anatomy, signal bus, outputs layout	aps-run-and-operate
Change model policy, hooks wiring, plists, contracts.json, add a flag	aps-config-and-flags
Figure out why a scheduled job is failing	aps-debugging-playbook
Know whether a change is safe to make at all	aps-change-control
History of past incidents and dead ends	aps-failure-archaeology
Measure fleet health	aps-diagnostics-and-tooling

---

Provenance and maintenance

Verified 2026-07-06 against the live repo (read-only):

• Submodule pins/remotes: read .gitmodules; init state via git submodule status (3 uninitialized on reference machine). Re-verify: cat .gitmodules && git submodule status.
• Parent remote: git remote get-url origin.
• venv rebuild commands: .claude/rules/python-runtime.md + heal_venv() in scripts/env_bootstrap.sh (they match). Re-verify: grep -n "uv venv" scripts/env_bootstrap.sh .claude/rules/python-runtime.md.
• env_bootstrap modes/behavior + gws launchd symlink + npm install hint: read the full script. Re-verify: bash scripts/env_bootstrap.sh --verify.
• required_clis + symlink entries: read env-parity.json. Re-verify: jq .required_clis env-parity.json.
• Headless auth: rule text + grep -rn headless.env scripts/skills/*.sh; file mode checked with ls -l ~/.config/claude-code/headless.env (0600). Re-verify with the AUTH_OK one-liner.
• Runner unset ANTHROPIC_API_KEY coverage (13 of 22; 9 lacking, listed in §5): measured 2026-07-06. Re-verify: grep -L 'unset ANTHROPIC_API_KEY' scripts/skills/run_*.sh.
• Media venv install commands: read from scripts/tts/voxcpm_tts.py (3.11.x auto-detect), scripts/stt/qwen_asr_stt.py, scripts/stt/diarize.py, scripts/tts/qwen3_tts.py (each embeds its own install hint). ~/.venvs contents listed (no pyannote yet). Re-verify: ls ~/.venvs && grep -n "pip install" scripts/tts/qwen3_tts.py scripts/stt/qwen_asr_stt.py scripts/stt/diarize.py.
• Machine registry + consumer: scripts/machine_registry.json, scripts/machine_label.py.
• sod/eod parity wiring: grep -n env_bootstrap .claude/skills/sod-ship/SKILL.md .claude/skills/eod-ship/SKILL.md.
• Go path + go.work ignores: ls -d ai-platform-webui/ai-platform/backend/go and grep -n go.work .gitignore ai-platform-webui/.gitignore; root ai-platform/ confirmed absent.
• Safety-gate .venv claim: full read of .claude/hooks/pre-tool-safety-gate.sh (80 lines, no venv pattern) — documented honestly in the traps table.

Drift-prone items: submodule pins (.gitmodules), required_clis, CLI install channels for hf/rtk (marked unverified), the webwright _note, pyannote venv presence, and the pyproject workspace-member path. Re-run the listed one-liners before trusting them after 2026-07.