docs: home lab coverage refresh (2026-05-22)#23
Merged
Conversation
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
JacobPEvans
added a commit
that referenced
this pull request
May 24, 2026
Removes coverage of repos kept out of the personal docs site: - terraform-aws-bedrock (test project, not part of the homelab story) - terraform-aws-static-website (being replaced by this docs site itself) - VisiCore App / TA (work-related — kept out of personal docs entirely) Changes: - Delete the four pages and their nav entries in docs.json - Strip cross-links from infrastructure/overview, infrastructure/ kubernetes-overview, infrastructure/secrets-sops, infrastructure/ terraform-runs-on, observability/overview, observability/ cc-edge-the-mac-pack, observability/monitoring-agents - Add a Step 1a coverage blacklist to the mintlify-docs-update skill so any future audit run filters these repos out before Step 2 categorization - Update the skill's "When NOT to use" section to drop references to the three closed sibling-skill issues; Claude edits pages directly for those concerns now - Add "blacklisted" to the Step-7 summary report's skip-reason enumeration Sensitive-content sweep: no real IPs, no 12-digit AWS account IDs, no non-allowlisted domains, no email addresses, no SSH/GPG keys in any remaining PR-#23 file. Assisted-by: Claude <noreply@anthropic.com>
JacobPEvans
added a commit
that referenced
this pull request
May 24, 2026
…tion, Cribl pack scope Four targeted refinements to the homelab docs refresh: - mintlify-docs-update SKILL.md: drop the "Step 1a" half-step numbering. The blacklist is a discrete sequential step, not a parallel sub-step; renumber the workflow 1-8 so every step is whole-numbered. - secrets-sops.mdx: reframe SOPS around blast radius, not rotation cadence. SOPS is the default for sensitive-but-not-mission-critical values where an AI-driven public leak would be a paper cut (randomly generated repo-local passwords, per-host config). It is NOT for external/cloud API tokens — those go to Doppler. It is NOT for cross-repo secrets unless one repo is fully dependent on another; otherwise it's a DRY violation. Added an explicit cross-repo decision tree. - New CI/CD sub-section nested under Infrastructure: created `infrastructure/cicd/overview.mdx` covering the GitHub Actions strategy (RunsOn AWS spot, OIDC, plan/apply pattern, secrets flow, branch protection). Moved `infrastructure/terraform-runs-on .mdx` → `infrastructure/cicd/terraform-runs-on.mdx`. Updated docs.json with the nested group and updated the two in-site cross-references in infrastructure/overview.mdx and infrastructure/secrets-sops.mdx. - cc-edge-the-mac-pack.mdx: trim the page to its homelab-integration scope. Cribl packs are standalone artifacts — full pack documentation (Sources, predicates, anomaly rules, override patterns, changelogs) belongs in the pack's own repo README. This page now covers only where the pack runs in our fleet, what indexes it populates, and how a new Mac joins the telemetry fleet. Reference to the repo README handles the rest. Assisted-by: Claude <noreply@anthropic.com>
Tier 2 topical deep-dive on the public Bedrock agent + Lambda URL deployment shape.
Tier 2 topical deep-dive on the reusable static-site module — CloudFront, S3, ACM, Route53 with encrypted, versioned, logged defaults.
Tier 2 topical deep-dive on the self-hosted GitHub Actions runners deployment — RunsOn v3 control plane on AWS, spot circuit breaker, OIDC apply, redacted PR plans.
Tier 2 topical deep-dive on the local OrbStack K8s cluster running the monitoring stack: OTEL Collector, Cribl Edge x2, Cribl Stream, MCP server, Bifrost AI gateway. Covers the Edge → Stream → Splunk architecture invariant.
Tier 2 topical deep-dive on the Splunk App's six Dashboard Studio v2 dashboards for AI coding tool observability — Overview, Token Usage, Cost, Tool Activity, Sessions, Cache Performance.
Tier 2 topical deep-dive on the Splunk Technology Add-on — field extractions for 20 sourcetypes, OTel GenAI semantic-convention aliases, Splunk CIM mappings, nine search macros, and the model-pricing lookup.
Tier 2 topical deep-dive on the macOS host telemetry pack — Cribl 4.18 native Sources for unified logs and system metrics, exec/file sources for thermal, powermetrics, battery health, snapshot files. Edge captures broadly, Stream filters.
Tier 2 framing of the IaC-flavored slice of SOPS — how it shows up in Ansible and Terraform repos, the three-way split with Doppler and Keychain, the rotation ritual. Complements the security/tools/sops tool-level page.
Tier 2 framing of the four-question decision tree — LXC default, Docker only when vendor leaves no native path. Documents the specific exceptions (Splunk, Qdrant, GHA runners) and the OrbStack/K8s split on macOS.
Tier 2 framing of the K8s philosophy — OrbStack on macOS as the local control plane, LXC + Ansible on Proxmox, no K8s on AWS. What runs on which platform and why. The Edge → Stream → Splunk invariant across both hosts.
Tier 2 cross-stack map — every Cribl Edge, Cribl Stream, OTel collector, REST collector, and the per-tool packs; where each runs and what it forwards to. The Edge → Stream → Splunk invariant across LXC, native macOS, and OrbStack K8s.
Wires up the 11 new MDX pages added in this branch into the Infrastructure and Observability groups in docs.json.
Adds links from infrastructure/overview, observability/overview, and about/homelab to the 11 new pages added in this branch. Existing prose unchanged.
Removes coverage of repos kept out of the personal docs site: - terraform-aws-bedrock (test project, not part of the homelab story) - terraform-aws-static-website (being replaced by this docs site itself) - VisiCore App / TA (work-related — kept out of personal docs entirely) Changes: - Delete the four pages and their nav entries in docs.json - Strip cross-links from infrastructure/overview, infrastructure/ kubernetes-overview, infrastructure/secrets-sops, infrastructure/ terraform-runs-on, observability/overview, observability/ cc-edge-the-mac-pack, observability/monitoring-agents - Add a Step 1a coverage blacklist to the mintlify-docs-update skill so any future audit run filters these repos out before Step 2 categorization - Update the skill's "When NOT to use" section to drop references to the three closed sibling-skill issues; Claude edits pages directly for those concerns now - Add "blacklisted" to the Step-7 summary report's skip-reason enumeration Sensitive-content sweep: no real IPs, no 12-digit AWS account IDs, no non-allowlisted domains, no email addresses, no SSH/GPG keys in any remaining PR-#23 file. Assisted-by: Claude <noreply@anthropic.com>
…tion, Cribl pack scope Four targeted refinements to the homelab docs refresh: - mintlify-docs-update SKILL.md: drop the "Step 1a" half-step numbering. The blacklist is a discrete sequential step, not a parallel sub-step; renumber the workflow 1-8 so every step is whole-numbered. - secrets-sops.mdx: reframe SOPS around blast radius, not rotation cadence. SOPS is the default for sensitive-but-not-mission-critical values where an AI-driven public leak would be a paper cut (randomly generated repo-local passwords, per-host config). It is NOT for external/cloud API tokens — those go to Doppler. It is NOT for cross-repo secrets unless one repo is fully dependent on another; otherwise it's a DRY violation. Added an explicit cross-repo decision tree. - New CI/CD sub-section nested under Infrastructure: created `infrastructure/cicd/overview.mdx` covering the GitHub Actions strategy (RunsOn AWS spot, OIDC, plan/apply pattern, secrets flow, branch protection). Moved `infrastructure/terraform-runs-on .mdx` → `infrastructure/cicd/terraform-runs-on.mdx`. Updated docs.json with the nested group and updated the two in-site cross-references in infrastructure/overview.mdx and infrastructure/secrets-sops.mdx. - cc-edge-the-mac-pack.mdx: trim the page to its homelab-integration scope. Cribl packs are standalone artifacts — full pack documentation (Sources, predicates, anomaly rules, override patterns, changelogs) belongs in the pack's own repo README. This page now covers only where the pack runs in our fleet, what indexes it populates, and how a new Mac joins the telemetry fleet. Reference to the repo README handles the rest. Assisted-by: Claude <noreply@anthropic.com>
JacobPEvans
force-pushed
the
docs/audit-docs-refresh
branch
from
9c56a92 to
0f11626
Compare
Three corrections to the new CI/CD section per Daisy's feedback: - Drop the "small, opinionated, uniform" framing. The CI/CD surface spans four runner tiers, not two. Expanded the runner-selection table to GitHub-hosted (public repos, free), RunsOn AWS spot (private repos, cheaper than GitHub), self-hosted Mac (every macOS-only requirement), and self-hosted locked-down (pre-built environments, tighter network/credential control). The decision is workload-first, not cost-first. - Remove the Tier 1/2/3 secrets-flow table from the CI/CD page. That material lives in /security/overview and is the source of truth — duplicating it here invites drift. Replaced with a one-line pointer that explicitly says this page does not re-doc secrets posture. - Strip budget/cost detail from terraform-runs-on.mdx. The repo ships its own README with current Budgets thresholds, alarm targets, and spend envelope; those numbers are tuned per deployment and don't belong in cross-repo docs. Kept a one-line pointer to that README. Assisted-by: Claude <noreply@anthropic.com>
JacobPEvans
added a commit
that referenced
this pull request
May 24, 2026
The CI/CD overview documented the four runner tiers but didn't say what a self-hosted runner has to actually be. The recurring token-refresh failure in orbstack-kubernetes (JacobPEvans/orbstack-kubernetes#234, #237) shows the cost of leaving this implicit. Adds a single subsection between "Runner tiers" and "The shape of every IaC pipeline" listing the five non-negotiables for any self-hosted runner: GitHub App auth (not PAT), digest-pinned image, process healthcheck, dead-man's-switch heartbeat, pre-flight secret check. Links to the orbstack-kubernetes runner as the reference implementation. Companion PRs codify the same rules at the AI-agent layer: - JacobPEvans/ai-assistant-instructions#654 (org-wide ci-cd-policy rule) - JacobPEvans/claude-code-plugins#321 (self-hosted-runners skill) Supersedes the earlier standalone runner-topology-page draft in this PR's history — the four-tier CI/CD section landed in #23 in the meantime, making a separate topology page redundant. Assisted-by: Claude <noreply@anthropic.com>
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Home lab docs coverage refresh from the 2026-05-22 audit.
New repo pages (7)
New gap-fill pages (4)
infrastructure/secrets-sops— SOPS+age slice as it shows up in Terraform and Ansible repos; three-way split with Doppler and Keychaininfrastructure/lxc-vs-docker— four-question decision tree; documented exceptions; OrbStack/K8s split on macOSinfrastructure/kubernetes-overview— OrbStack-as-control-plane philosophy; what runs on K8s vs LXC vs Dockerobservability/monitoring-agents— cross-stack map of every Cribl Edge, Stream, OTel collector, REST collector, per-tool packCross-links
Added link sentences in
infrastructure/overview.mdx,observability/overview.mdx, andabout/homelab.mdxto point at the new pages.Queued as separate docs issues (need user input)
Verification
mint broken-links:success no broken links foundmint dev: starts and serves (returns HTTP 307 from/as expected for Mintlify landing redirect)Hard rules respected