docs: fix CLAUDE.md, restructure README, verify docs/ (#426) #431
No reviewers
Labels
No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
ldraney/pal-e-platform!431
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "426-docs-audit"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Fixes stale CLAUDE.md, restructures README as a documentation TOC, and creates five new docs/ files covering architecture, monitoring, database, networking, and secrets.
Changes
admin), dashboard count (4 -> 8), repo URLs (github.com -> forgejo), removed inline content moved to docs/Test Plan
ls terraform/modules/ls terraform/dashboards/terraform/versions.tfReview Checklist
Related Notes
None -- docs-only change, no pal-e-docs notes affected.
Related
Closes #426
PR #431 Review
DOMAIN REVIEW
Tech stack: OpenTofu IaC, Kubernetes (k3s), Helm, Tailscale, SaltStack, CNPG. This is a docs-only PR -- no infrastructure changes. Review focused on factual accuracy of documentation against the actual repo contents.
Verification method: Cross-referenced every numeric claim (module count, dashboard count, provider count, secret count, funnel count, namespace count) against the actual files on
main.Fact-check results:
terraform/modules/terraform/dashboards/terraform/versions.tfMakefileterraform/modules/networking/main.tfkubernetes_ingress_v1resourcesterraform/network-policies.tfterraform/main.tfProvider version constraints in
docs/architecture.mdmatchterraform/versions.tfexactly.Network policy matrix in
docs/networking.mdmatchesterraform/network-policies.tfexactly -- every namespace and every allowed ingress source verified line by line.Secret inventory in
docs/secrets.mdmatchesMakefileTF_SECRET_VARSexactly -- all 26 variables present with correct usage descriptions.Dashboard inventory in
docs/monitoring.mdmatchesterraform/dashboards/filenames exactly.Content coverage: The old README's inline sections (Key Design Decisions, GitOps Pipeline, Observability, Tech Stack) are fully covered by the new docs:
docs/networking.mddocs/secrets.mddocs/architecture.mdState Management sectiondocs/monitoring.mdDORA Exporter sectiondocs/architecture.mddependency graphdocs/monitoring.md(corrected from 4 to 8)CLAUDE.mdTech Stack sectionOld stale claims fixed:
admin). Fixed.github.com. Fixed toforgejo.tail5b443a.ts.net.BLOCKERS
None.
NITS
Dependency graph in
docs/architecture.mdis slightly misleading. The ASCII graph impliesnetworkingis independent (top of the graph), butnetworkingactually takes namespace outputs from 7 other modules (monitoring,forgejo,ci,harbor,storage,keycloak,admin). These are implicit data dependencies through variable references, not explicitdepends_on, but the graph gives the impression thatnetworkinghas no dependencies. Consider adding a note thatnetworkinghas implicit dependencies via namespace inputs.docs/superpowers/not linked from README. Thedocs/directory contains 7 plans/specs underdocs/superpowers/(plans and design specs from March-May 2026). The README Documentation table links only to the 5 new docs + 3 existing docs. The superpowers/ directory is unlisted. Not a blocker since those are historical spike/plan artifacts, but a brief mention or link would make the TOC complete.minio_oidc_client_secretundocumented.terraform/variables.tfdefines aminio_oidc_client_secretvariable (sensitive,default = ""). It is not in the Makefile'sTF_SECRET_VARSlist, which is whydocs/secrets.mdcorrectly omits it from the pipeline inventory. However, it exists as an optional variable that could be set. A brief mention indocs/secrets.mdabout optional secrets (those with defaults that are not part of the validation pipeline) would prevent future confusion when someone finds it invariables.tf.docs/networking.mdfunnel table omits hostname column. Each funnel creates a specific*.tail5b443a.ts.nethostname. The table lists Service and Namespace Source but not the actual hostname. Adding the hostname (e.g.,grafana.tail5b443a.ts.net) would make the inventory more operationally useful.docs/architecture.mdmodule inventory:opsmodule description. The table says the ops module manages "NVIDIA device plugin (Helm), embedding worker metrics service, tofu state backup CronJob". This omits Ollama, which the README module table correctly includes ("NVIDIA GPU plugin, Ollama, embedding worker, tofu state backup CronJobs"). The architecture doc should match.SOP COMPLIANCE
PROCESS OBSERVATIONS
VERDICT: APPROVED
PR #431 Review
DOMAIN REVIEW
Tech stack: Terraform/OpenTofu IaC (docs-only change -- no HCL modified). 7 files changed: CLAUDE.md, README.md, and 5 new docs/ files (architecture.md, database.md, monitoring.md, networking.md, secrets.md).
Verification against live repo state:
terraform/modules/terraform/dashboards/CLAUDE.md assessment: Properly thin and dev-focused. Contains: tech stack (5 providers, state backend, secrets pipeline, Salt), key paths (12 entries covering root TF files, modules, salt, Makefile, docs), running commands (make targets for tofu and salt), PR conventions. No agent dispatch boilerplate, no roadmap, no inline content that belongs in docs/. Old version had wrong state backend ("local" vs kubernetes), only 3 providers, and stale agent dispatch section -- all fixed.
README assessment: Successfully restructured as TOC. Module table updated from 10/11 to 12 (added
admin). Dashboard count corrected from 4 to 8. Repo URLs corrected from github.com to forgejo.tail5b443a.ts.net. Inline sections (Key Design Decisions, GitOps Pipeline, Observability, detailed Tech Stack) properly migrated to docs/ files. Documentation table links all 8 doc files.BLOCKERS
None.
NITS
Dependency graph diagram incomplete (docs/architecture.md): The ASCII diagram shows
forgejo --> cibut omits thedatabase --> ciarrow. The parenthetical annotation "(depends_on: forgejo, database)" is correct, but the visual graph is misleading -- a reader scanning the diagram would miss thatdatabaseis also a dependency ofci. Suggest adding adatabasenode with an arrow toci..claude-no-enforcepresent in working tree: Confirmed this file exists at repo root but is NOT in the PR diff, so it is not being committed. Just flagging for awareness -- ensure.gitignorecovers it if it should never be committed.SOP COMPLIANCE
## Summary## Changes(detailed per-file breakdown)## Test Plan(4 verification items with checkboxes)## Related(Closes #426)PROCESS OBSERVATIONS
VERDICT: APPROVED