Compare commits
2 Commits
c634612ad2
...
5beda180d6
| Author | SHA1 | Date | |
|---|---|---|---|
|
5beda180d6 | ||
|
|
570e96fff8 |
43
CLAUDE.md
43
CLAUDE.md
@ -2,7 +2,15 @@
|
||||
|
||||
This file is the spec for this vault. Any agent operating on this vault
|
||||
reads this file first. Procedures (compile, lint, migration) live in the
|
||||
`wiki-maintenance` skill on herbydev — this file is the spec they reference.
|
||||
`wiki-maintenance` skill — this file is the spec they reference.
|
||||
|
||||
> **Canonical schema source.** The `vault-mcp` server's
|
||||
> `vault_mcp/core/schema.py` (returned via the `vault:get_schema` MCP
|
||||
> tool) is the **authoritative** vocabulary for note types, statuses,
|
||||
> domains, and folder paths. If this CLAUDE.md and that schema
|
||||
> disagree, the schema wins — update this file. The
|
||||
> vocabulary listed below mirrors `schema.py` as of the last touch;
|
||||
> bump in sync.
|
||||
|
||||
## Purpose
|
||||
|
||||
@ -16,7 +24,10 @@ two-layer structure.
|
||||
### Layer 1: Sources
|
||||
|
||||
Raw project plans and session notes. Written by Travis, Jenny, and LLM
|
||||
agents via the homelab MCP server. These are the input to the compile loop.
|
||||
agents via the `vault-mcp` server (formerly called `homelab-mcp-server`
|
||||
/ `herbydev-mcp`). New writes flow through `vault:create_artifact` —
|
||||
which dual-writes a Postgres row in `petalbrain.wiki` and a markdown
|
||||
file here. These are the input to the compile loop.
|
||||
|
||||
Location: `Sources/<Domain>/`
|
||||
|
||||
@ -43,6 +54,9 @@ At the vault root:
|
||||
- `CLAUDE.md` — this file
|
||||
- `index.md` — navigation front door
|
||||
- `log.md` — append-only compile audit trail
|
||||
- `migrate.py` — one-shot migration script from the prior
|
||||
pbs-projects / homelab-projects layout (run once on
|
||||
initial vault creation; not part of the steady-state)
|
||||
|
||||
## Four Ownership Domains
|
||||
|
||||
@ -66,7 +80,7 @@ shaped, pick one domain and tag with the others.
|
||||
---
|
||||
project: <slug>
|
||||
type: project-plan
|
||||
status: active # active | paused | completed | archived
|
||||
status: <status> # see canonical statuses below
|
||||
path: Sources/<Domain>
|
||||
tags:
|
||||
- <tag>
|
||||
@ -75,6 +89,24 @@ updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
**Canonical statuses** (from `vault-mcp/vault_mcp/core/schema.py`):
|
||||
|
||||
| Status | Meaning |
|
||||
|-------------|---------------------------------------------------------|
|
||||
| `idea` | Captured, not yet committed to |
|
||||
| `planned` | Committed but not started |
|
||||
| `on_deck` | Next up — default for newly-created projects |
|
||||
| `active` | Currently in progress |
|
||||
| `blocked` | Waiting on something external |
|
||||
| `completed` | Finished — no further work expected |
|
||||
| `killed` | Abandoned (vs. `completed`, which implies success) |
|
||||
|
||||
`vault-mcp` fires a Postgres `NOTIFY` on project-status changes that
|
||||
n8n turns into Trello card moves — so changing a status via
|
||||
`vault:update_artifact` propagates downstream. Hand-editing the
|
||||
frontmatter does **not** fire the NOTIFY; use the MCP tool when
|
||||
possible.
|
||||
|
||||
**Required sections:**
|
||||
- `## Goal` — one paragraph, what this project achieves
|
||||
- `## Locked Decisions` — bulleted, dated as needed
|
||||
@ -89,8 +121,9 @@ updated: YYYY-MM-DD
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
project: <slug>
|
||||
type: session-notes
|
||||
project: <slug> # parent project's slug — required
|
||||
type: session-notes # plural form is canonical (some legacy files
|
||||
# have `session-note` singular; lint should fix)
|
||||
status: active
|
||||
path: Sources/<Domain>
|
||||
tags:
|
||||
|
||||
87
README.md
Normal file
87
README.md
Normal file
@ -0,0 +1,87 @@
|
||||
# wiki-vault
|
||||
|
||||
Travis's personal knowledge vault — project plans, session notes, and
|
||||
a compiled LLM-maintained wiki. Two layers, four ownership domains,
|
||||
versioned in git, indexed in `petalbrain` Postgres, and embedded for
|
||||
semantic search via Ollama.
|
||||
|
||||
## Where to start
|
||||
|
||||
| File | Purpose |
|
||||
|--------------|----------------------------------------------------------|
|
||||
| `CLAUDE.md` | **The spec.** Vault structure, page types, frontmatter, status vocabulary, git protocol. Agents read this first. |
|
||||
| `index.md` | Navigation front door — links into Sources and Wiki indexes. |
|
||||
| `log.md` | Append-only audit log of compile / lint / migration runs. |
|
||||
|
||||
If you're an agent acting on this vault, read `CLAUDE.md`. If you're a
|
||||
human browsing, start at `index.md`.
|
||||
|
||||
## Two-layer structure
|
||||
|
||||
```
|
||||
wiki-vault/
|
||||
├── Sources/ # Raw — input to the compile loop
|
||||
│ ├── Dev/
|
||||
│ ├── Venture/
|
||||
│ ├── Homelab/
|
||||
│ └── Reference/
|
||||
└── Wiki/ # Compiled output — generated by wiki-maintenance
|
||||
├── Dev/
|
||||
├── Venture/
|
||||
├── Homelab/
|
||||
└── Reference/
|
||||
```
|
||||
|
||||
- **Sources** = raw project plans + session notes, written by Travis,
|
||||
Jenny, and LLM agents through `vault-mcp`.
|
||||
- **Wiki** = compiled entity pages, topic landings, and synthesis —
|
||||
produced and maintained by the `wiki-maintenance` skill. Never
|
||||
written to directly outside the compile loop.
|
||||
|
||||
## How it gets written
|
||||
|
||||
| Path | Who writes it |
|
||||
|-------------------------------------|--------------------------------------------------------------|
|
||||
| `Sources/<Domain>/<slug>.md` | `vault-mcp:create_artifact` (project plans) |
|
||||
| `Sources/<Domain>/YYYY-MM-DD-*.md` | `vault-mcp:create_artifact` (session notes) |
|
||||
| `Wiki/...` | `wiki-maintenance` skill, during compile runs only |
|
||||
| `index.md`, `Sources/index.md`, `Wiki/index.md`, `<Domain>/index.md` | Compile loop |
|
||||
| `log.md` | Compile / lint / migration runs (append-only) |
|
||||
|
||||
`vault-mcp` dual-writes: Postgres row in `petalbrain.wiki` for index +
|
||||
embeddings, markdown file here for canonical content. The repo is
|
||||
configured for HTTPS push to gitea via a PAT-backed credential helper
|
||||
— see `vault-mcp/CLAUDE.md` for the mechanics.
|
||||
|
||||
## Git protocol
|
||||
|
||||
Every mutation lands as a tracked commit with a typed prefix:
|
||||
|
||||
| Prefix | Source |
|
||||
|--------------------|-------------------------------------------------|
|
||||
| `mcp: <kind> — …` | `vault-mcp` writes (project-plan or session-notes) |
|
||||
| `pre-compile: …` | Snapshot before a compile run touches anything |
|
||||
| `compile: …` | Compile run body — pages touched/created/promoted |
|
||||
| `lint: …` | Auto-fixes from the linter |
|
||||
|
||||
Two-commit pattern on compile runs (`pre-compile` then `compile`) so
|
||||
the diff of the run is reviewable in isolation.
|
||||
|
||||
## Quick operational notes
|
||||
|
||||
- **Don't edit `Wiki/` by hand.** The compile loop owns it. Edits get
|
||||
overwritten on the next run.
|
||||
- **Don't add tags silently.** New tags need explicit user approval
|
||||
or 3+ pages of usage.
|
||||
- **Don't delete pages without confirmation.** The compile loop has
|
||||
archive semantics — work through it, not around it.
|
||||
- **Status changes flow through `vault-mcp:update_artifact`** when
|
||||
possible — that's what fires the Postgres `NOTIFY` that n8n turns
|
||||
into Trello card moves. Hand-edits to frontmatter skip the
|
||||
automation.
|
||||
|
||||
## Repo
|
||||
|
||||
- Origin: gitea `petal-power/wiki-vault` (HTTPS push via `vault-mcp`'s
|
||||
PAT credential helper).
|
||||
- This vault is mounted into the `vault-mcp` container at `/vault`.
|
||||
133
Sources/Dev/repo-hygiene-remediation.md
Normal file
133
Sources/Dev/repo-hygiene-remediation.md
Normal file
@ -0,0 +1,133 @@
|
||||
---
|
||||
created: '2026-05-20'
|
||||
path: Sources/Dev
|
||||
project: repo-hygiene-remediation
|
||||
tags:
|
||||
- repo-hygiene
|
||||
- documentation
|
||||
- dev
|
||||
- cleanup
|
||||
- security
|
||||
- audit
|
||||
- git
|
||||
- ansible
|
||||
type: project-plan
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Remediate every finding and due-out surfaced by the documentation audit of 2026-05-19/20 (the "guided review of all the project folders" pass), and stand up a lightweight recurring process so the project folders don't drift back into inconsistency.
|
||||
|
||||
The audit touched 23 repos across four domain folders, created/fixed ~45 doc files (~4,400 lines), and surfaced a deduped list of ~20 findings spanning security, blocked repos, cross-repo cleanups, and policy decisions. Those findings are the backlog this plan works through. This plan is **hygiene-scoped only** — it does NOT absorb the unrelated feature/initiative work from the same working session (reflector follow-ups, scene-management deploy, pbs-hub-mcp landing, enricher migration) — those live in their own threads and are cross-referenced below.
|
||||
|
||||
---
|
||||
|
||||
## Starting Condition (Phase 0 gate)
|
||||
|
||||
**`herbys-dev-setup` must be completed before this plan's work begins.** The dev-environment hardening that project covers (Proxmox / Tailscale / dev-environment baseline) is the foundation this hygiene work sits on top of — no point hardening repo hygiene on a dev environment that's still being hardened underneath it. Treat Phase 0 as a hard gate: confirm `herbys-dev-setup` is at `completed` status before opening Phase 1.
|
||||
|
||||
---
|
||||
|
||||
## Context — what the audit found
|
||||
|
||||
The 23 doc commits are sitting **local and unpushed** on `docs-audit` branches (clean repos) or as doc-only commits on existing default branches (dirty repos). Travis reviews via git and pushes/merges himself. The audit also confirmed a structural truth that motivated this plan: documentation drifts silently, and a one-time sweep isn't enough — a recurring review is needed.
|
||||
|
||||
Audit commit log (all local, none pushed):
|
||||
- homelab: trellis-mcp `7188a4f`, vault-mcp `82bccc6`, homelab-ansible `61e0f6c`, OB1 `eab4416`, ob1-deploy `e6b5e6e`, hunyuan3d-sunnie `8c88adc`, instamesh-docker `5cff79d`
|
||||
- pbs: a-review-skill `a3accf2`, Claude-Code-Scaffolding-Skill `4e062eb`, cli-standardization `69681a0`, docker-container `8b825e6`, dotfiles `c03d203`, python-uv `a3ad752`, session-notes-skill `3fe5478`, work-index-dashboard `25a0a07`, ssh-login-alerter `0de0e9a`
|
||||
- docker: authelia `31b66d2`, authentik `fc640be`, cloudflared `2f4fc25`, n8n `04c995d`, traefik `15b42bc`
|
||||
- root: wiki-vault `570e96f`, wiki-context `1435726`
|
||||
|
||||
---
|
||||
|
||||
## Locked Decisions / Conventions
|
||||
|
||||
- **md files only.** The audit and this remediation touch CLAUDE.md / README.md only unless a phase explicitly says otherwise. Source/config/vendored files are out of scope per-phase unless called out.
|
||||
- **Travis pushes GitHub-destined repos manually.** Gitea-destined repos can auto-push. Audit doc commits all wait for Travis's git review.
|
||||
- **Doc-role split:** README = human onboarding; CLAUDE.md = agent operating guide (concise, gotcha-focused, not a README clone).
|
||||
- **docker compose stacks get README only**, no per-stack CLAUDE.md. Non-git docker dirs need `git init` before they can be doc'd/reviewed.
|
||||
- **Audit methodology (reusable for the recurring review):** score each doc on accuracy (heaviest) → freshness → internal contradiction → completeness rubric → role fit. Verify documented commands/paths against the real tree; a confidently-wrong doc is worse than a missing one.
|
||||
|
||||
---
|
||||
|
||||
## Open Items (decisions needing Travis input)
|
||||
|
||||
1. **`python-uv` tracking policy** — pure upstream mirror of `a5chin/python-uv`, zero Travis commits (all 137 recent commits are upstream/dependabot). Decide: live tracker (keep rebasing) vs frozen snapshot (this audit is the cutoff).
|
||||
2. **`OB1` fork policy** — upstream community project (Nate B. Jones). README left as upstream-canonical; CLAUDE.md lightly fixed. Same tracker-vs-snapshot question as python-uv; contributor/dependabot PRs may collide with local doc edits.
|
||||
3. **`cli-standardization` name vs scope** — has outgrown its name (now a full Arch workstation orchestrator, 5 roles). Rename the repo (`workstation-ansible`? `pbs-workstation`?) + update gitea remote, OR redefine the name to mean "the standard way we provision a workstation."
|
||||
4. **`docker/authelia` secrets** — JWT/session/storage-encryption hex committed inline in compose.yml (different from the `.env` boundary the rest of docker/ uses). Extract to `.env`, rotate-and-recommit if ever public, or accept as-is for a private repo.
|
||||
5. **`docker/n8n_server` (non-git dir)** — the live `n8n/` stack consumes its external volume (`n8n_server_n8n_data`). Confirm whether `n8n_server/` is retired (remove) or still load-bearing (version-control it).
|
||||
6. **Recurring-review cadence + owner** — who/what drives the periodic guided review (Phase 7). Travis's quip "not sure who is doing the guiding" is the live question: cadence (monthly? per-merge?), and whether it's a skill, a scheduled task, or a manual checklist.
|
||||
|
||||
---
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 0 — Starting condition (gate)
|
||||
- [ ] Confirm `herbys-dev-setup` is at `completed` status. Do not start Phase 1 until it is.
|
||||
|
||||
### Phase 1 — Land the audit's doc commits
|
||||
Review and ship the 23 local doc commits.
|
||||
- [ ] `git diff` review each `docs-audit` branch (clean repos) — 12 branches.
|
||||
- [ ] Review the 11 doc-only commits on existing default branches (dirty repos) — confirm they only touched md files (already verified by the audit, but spot-check).
|
||||
- [ ] Merge/push per repo following the manual-push rule for GitHub-destined repos; auto-push acceptable for gitea-destined.
|
||||
- [ ] For dirty repos where the doc commit sits alongside unrelated uncommitted work (ob1-deploy, hunyuan3d-sunnie, instamesh-docker, Claude-Code-Scaffolding-Skill, work-index-dashboard, the 4 dirty docker stacks, wiki-vault), decide how to sequence the doc commit vs the in-flight work.
|
||||
|
||||
### Phase 2 — Security remediation
|
||||
- [ ] `docker/authelia/compose.yml` inline secrets — resolve per Open Item #4.
|
||||
- [ ] `docker/traefik/.env` is world-readable (0664) → tighten to 0600/0660.
|
||||
- [ ] Sweep `.env` permissions across all `docker/*` stacks — normalize to 0660 (or 0600).
|
||||
- [ ] Confirm no other secrets are committed in compose files across the docker domain.
|
||||
|
||||
### Phase 3 — Unblock un-auditable repos
|
||||
- [ ] `pbs/pbsii` + `pbs/zero-check-pipeline` — dubious .git ownership. Fix via `chown -R` or `git config --global --add safe.directory <path>`, then audit their docs.
|
||||
- [ ] `homelab/sshkm` — has no `.git` despite the global CLAUDE.md asserting it exists. Either re-init + push to gitea, or correct the global CLAUDE.md to match reality.
|
||||
- [ ] `docker/` non-git dirs (cloudbeaver, it-tools, n8n_server, obsidian, ollama, postgres) — `git init` + initial commit with `.env` gitignored from the start, then README each. Resolve the n8n_server retired-vs-live question (Open Item #5) first.
|
||||
- [ ] `homelab/second-brain` + `homelab/shared` — no .git; decide whether to version-control (they have real content) or leave as local-only scaffolding.
|
||||
- [ ] `pbs/youtube-analytics` — zero commits, everything untracked. Initial commit pass, then doc audit.
|
||||
- [ ] `pbs/wordpress-install` — finish or stash the dirty `staging`-branch work (10 modified ansible files), then audit its docs.
|
||||
|
||||
### Phase 4 — Cross-repo cleanups
|
||||
- [ ] `uv init` leftovers (`main.py` / `pyproject.toml` / `uv.lock` / `.python-version` / `.venv/`) in ~10 non-Python repos (docker-container, work-index-dashboard, ssh-login-alerter, hunyuan3d-sunnie, instamesh-docker, and the docker stacks authelia/cloudflared/n8n/traefik). Sweep-remove where they're not part of the build path.
|
||||
- [ ] `herbygitea` SSH-alias residue — the alias was removed from `~/.ssh/config`; the audit caught + fixed lingering references in cli-standardization/CLAUDE.md and dotfiles/README.md. Grep the whole tree (config files, scripts, gitea remotes) for remaining references.
|
||||
- [ ] `Claude-Code-Scaffolding-Skill/project-scaffolding/SKILL.md` still says "14 types" in frontmatter (missing the 3 Ansible types). It's the description Claude Code surfaces, so it's load-bearing — update + repack the `.skill`.
|
||||
- [ ] `docker/cloudflared` — finish the in-flight `docker-compose.yml → compose.yml` rename (`git rm docker-compose.yml && git add compose.yml`).
|
||||
- [ ] `docker/traefik` — decide if the debug-state compose (`--api.insecure=true`, port 8080, 443 commented out) is becoming the new normal; if so, update the README gotchas.
|
||||
- [ ] `pbs/work-index-dashboard` — stale `GEMINI.md` / `gemini-review-2026-04-27.md` (untracked). Remove or move into a `reviews/` subdir per the convention the new CLAUDE.md documents.
|
||||
- [ ] `pbs/ssh-login-alerter` — references an Ansible role that doesn't exist in the repo yet. Verify the role landed somewhere reachable (likely the broader pbs platform repo) before next deployment.
|
||||
|
||||
### Phase 5 — Deferred audits (post-conditions)
|
||||
- [ ] `pbs/pbs-video-manager` — re-audit CLAUDE.md/README after the 5-branch stack (scene-management → web-bp-csrf → scene-management-ux-fixes → phase1-paste-import → phase1-api-reads) merges to main. Docs are mid-flight on the stack; auditing now would conflict.
|
||||
- [ ] `homelab/OB1` ~100 component READMEs (recipes/skills/extensions/primitives/integrations/schemas/dashboards) — templated batch pass with a shared format. Define the canonical component-README template first; do NOT review one-at-a-time. (Coordinate with OB1's upstream-fork policy, Open Item #2.)
|
||||
- [ ] `docker/` non-git dirs — audit their READMEs once Phase 3 puts them under git.
|
||||
|
||||
### Phase 6 — Policy decisions (close the Open Items)
|
||||
- [ ] Resolve python-uv tracking policy (#1).
|
||||
- [ ] Resolve OB1 fork policy (#2).
|
||||
- [ ] Resolve cli-standardization rename-vs-redefine (#3).
|
||||
- [ ] Document whatever's decided in the relevant CLAUDE.md so future agents inherit the call.
|
||||
|
||||
### Phase 7 — Establish the recurring guided review
|
||||
The audit proved a one-time sweep isn't durable. Stand up a lightweight recurring process.
|
||||
- [ ] Decide cadence + owner (Open Item #6) — monthly? per-major-merge? triggered by a scheduled task?
|
||||
- [ ] Capture the audit methodology (the 5-dimension rubric + the enumeration approach) as a reusable artifact — candidate: a `repo-hygiene` skill or a checklist doc, so the next review doesn't have to re-derive the method.
|
||||
- [ ] Consider a canonical CLAUDE.md skeleton for the homelab so new repos start consistent (purpose / architecture / build+test+run / gotchas / don't-touch zones).
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
### Cross-references (NOT absorbed into this plan — tracked separately)
|
||||
- `herbys-dev-setup` — the Phase 0 starting-condition gate.
|
||||
- `pbs-hub-scene-management` (trellis: paused) — its branch stack must merge before pbs-video-manager docs can be re-audited (Phase 5).
|
||||
- `pbs-hub-data-import-and-mcp` (trellis: active) — pbs-hub-mcp is a new repo; its docs were rubber-stamped clean in the audit.
|
||||
- `postgres-consolidation-reflection-layer` + `ob1-reflector-post-launch-followups` (trellis: paused) — unrelated feature work; the audit only touched their repos' docs.
|
||||
- `env-file-hardening` — overlaps with Phase 2 (the .env permission + secrets-boundary work). Coordinate so the two don't duplicate.
|
||||
|
||||
### Process learnings from the audit (worth keeping)
|
||||
- Cowork workspace trust is per-exact-folder, not recursive. Pre-trust the domain subfolders, or route multi-folder work through one already-trusted session.
|
||||
- `start_code_task` timeouts can still spawn the task — never blind-retry (caused 3 redundant agents on the homelab batch; converged harmlessly only because those repos weren't worktree-isolated).
|
||||
- Routing a multi-folder batch through a single trusted session worked cleanly and avoided both the trust prompts and the duplicate-spawn risk.
|
||||
|
||||
### Scope discipline
|
||||
This plan is repo-hygiene only. Feature/initiative due-outs from the same working session are explicitly out of scope and live in their own trellis threads + vault plans. If a hygiene item turns out to need feature work (e.g., sshkm needs to actually be built, not just doc'd), spin that out rather than absorbing it here.
|
||||
Loading…
Reference in New Issue
Block a user