Erich Blume
db0512b5d4
## Doc review (5 stalest, all never-reviewed) Each card was verified against live state (ArgoCD app list/health, manifests, 1Password item fields, Mealie API probe) and stamped `last-reviewed: 2026-06-09`. | Card | Findings fixed | |------|----------------| | `reference/services/argocd.md` | Added Authentik SSO (public PKCE client, `--sso` login, admins→role:admin RBAC); documented dual-cluster management (minikube + ringtail k3s at `ringtail.tail8d86e.ts.net:6443`); corrected sync policy — the `apps` root is **manual**, not automated | | `reference/services/authentik.md` | Blueprint list grown from 5 to 10 files; OIDC client table now lists all 8 clients with types; secrets table updated to `postgresql-*` fields and per-client secrets | | `reference/services/grafana.md` | TeslaMate datasource moved to `pg.ops.eblu.me:5434` (ringtail); dashboard inventory refreshed (20 provisioned ConfigMaps); TeslaMate dashboards documented as init-container fetch from forge mirror at pinned tag; SSO role mapping wording corrected (Admin only for `admins` group) | | `reference/infrastructure/unifi.md` | UnPoller image is now locally built (`registry.ops.eblu.me/blumeops/unpoller`); verified namespace/port | | `how-to/mealie/plan-a-meal.md` | Procedure verified; **found the stored API token (`op://blumeops/mealie/credential`) returns 401** — operational fix in progress, doc content unchanged | ## AGENTS.md - **Scaled back the ai-docs rule** (per discussion): agents now start by finding and reading relevant docs; `mise run ai-docs` (~130K tokens now) and `ai-sources` become opt-in bulk loads. `agent-change-process.md` updated to match. The `ai-docs` mise task itself is kept for now — happy to retire it in a follow-up if desired. - **Documented the heph CLI** task workflow (list/show/context/log read paths; done/drop/skip/log/edit/task write paths) so future sessions can read and manipulate Blumeops tasks without rediscovery. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: #373
142 lines
5.3 KiB
Markdown
142 lines
5.3 KiB
Markdown
---
|
|
title: AI Assistance Guide
|
|
modified: 2026-06-09
|
|
tags:
|
|
- tutorials
|
|
- ai
|
|
---
|
|
|
|
# AI Assistance Guide
|
|
|
|
> **Audiences:** AI, Owner
|
|
|
|
This guide provides context for AI agents assisting with BlumeOps operations, and helps Erich understand how to work effectively with AI assistance.
|
|
|
|
## Critical Rules
|
|
|
|
These are non-negotiable for AI agents working in this repo:
|
|
|
|
1. **Always use `--context=minikube-indri` with kubectl** - Work contexts exist that must never be touched
|
|
2. **Start every task by finding and reading the relevant docs** - Grep `docs/` and follow wiki-links
|
|
3. **Never commit secrets** - The repo is public at github.com/eblume/blumeops
|
|
4. **Wait for user review before deploying** - Create PRs, don't auto-deploy
|
|
5. **Never merge PRs without explicit request** - The user merges after review
|
|
|
|
Full rules are in the repo's `AGENTS.md`. See [[agent-change-process]] for the C0/C1/C2 change classification methodology — C0 (direct to main), C1 (feature branch + PR), C2 (Mikado Branch Invariant).
|
|
|
|
## Workflow Conventions
|
|
|
|
### Branching
|
|
|
|
Branching depends on change classification (see [[agent-change-process]]):
|
|
|
|
- **C0 (Quick Fix):** Commit directly to main — no branch or PR needed
|
|
- **C1/C2:** Feature branch required:
|
|
```bash
|
|
git checkout main && git pull
|
|
git checkout -b feature/descriptive-name
|
|
# ... make changes ...
|
|
git commit -m "Description"
|
|
```
|
|
|
|
### Pull Requests
|
|
|
|
Use the forge's `tea` CLI:
|
|
```bash
|
|
tea pr create --title "Title" --description "$(cat <<'EOF'
|
|
## Summary
|
|
- Change 1
|
|
- Change 2
|
|
|
|
## Deployment and Testing
|
|
- [ ] Test step
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
### Changelog Fragments
|
|
|
|
Add a fragment for user-visible changes:
|
|
```bash
|
|
# C1/C2: use branch name
|
|
echo "Description" > docs/changelog.d/branch-name.feature.md
|
|
|
|
# C0: use orphan prefix (no branch to name after)
|
|
echo "Description" > docs/changelog.d/+descriptive-slug.feature.md
|
|
```
|
|
|
|
Types (file suffix): `.feature`, `.bugfix`, `.infra`, `.doc`, `.ai`, `.misc`
|
|
|
|
### Wiki-Link Formatting
|
|
|
|
Use simple wiki-links without alternate text or extra spaces:
|
|
- Prefer `[[borgmatic]]` over `[[borgmatic|Borgmatic]]`
|
|
- Only use alternate text when grammatically warranted (e.g., `[[cluster|Kubernetes]]` reads better than `[[cluster]]`)
|
|
- No spaces around the pipe: `[[path|Text]]` not `[[ path|Text ]]`
|
|
|
|
When editing documentation, rewrite links to follow this convention as you encounter them.
|
|
|
|
## Service Locations
|
|
|
|
Understanding where services run helps target changes correctly:
|
|
|
|
| Location | Services | Management |
|
|
|----------|----------|------------|
|
|
| [[indri]] (native) | Forgejo, Zot, Jellyfin, Caddy | Ansible |
|
|
| [[cluster|Kubernetes]] | Everything else | ArgoCD |
|
|
|
|
## Mise Tasks
|
|
|
|
BlumeOps operations are driven by mise tasks. Run `mise tasks` to list all available tasks.
|
|
|
|
| Task | When to Use |
|
|
|------|-------------|
|
|
| `ai-sources` | Deep context - all non-doc source files (~270K tokens). Ask user before running; useful for problems with a large surface area (see [[mise-tasks]]) |
|
|
| `docs-mikado` | View active Mikado dependency chains for C2 changes |
|
|
| `docs-mikado --resume` | Resume a C2 chain: detect branch, show state and next steps |
|
|
| `provision-indri` | Deploy changes to [[indri]]-hosted services via Ansible |
|
|
| `services-check` | After deployments - verify all services are healthy |
|
|
| `pr-comments` | Check unresolved PR comments during review |
|
|
| `container-list` | View available container images and tags |
|
|
| `container-build-and-release` | Trigger container build workflows |
|
|
| `dns-preview` | Preview DNS changes before applying |
|
|
| `dns-up` | Apply DNS changes via Pulumi |
|
|
| `tailnet-preview` | Preview Tailscale ACL changes |
|
|
| `tailnet-up` | Apply Tailscale ACL changes via Pulumi |
|
|
| `docs-check-links` | Validate wiki-links resolve correctly (supports path-based links, orphan detection) |
|
|
| `docs-review-stale` | Report docs by last-modified date, highlight stale ones |
|
|
| `docs-review-tags` | Print frontmatter tag inventory across all docs |
|
|
| `docs-review` | Review the most stale doc by last-reviewed date |
|
|
| `runner-logs` | View Forgejo workflow logs (indri or ringtail runner) |
|
|
|
|
For task discovery, BlumeOps tasks live in [hephaestus](https://github.com/eblume/hephaestus) (`heph`), not Todoist. List outstanding work with `heph list --project Blumeops --json`.
|
|
|
|
For ArgoCD operations, use the `argocd` CLI directly:
|
|
- `argocd app diff <service>` - Preview changes
|
|
- `argocd app sync <service>` - Deploy changes
|
|
|
|
## Reference Navigation
|
|
|
|
For AI agents building context:
|
|
|
|
- [Reference](/reference/) - Entry point for technical details
|
|
- [[hosts|Host Inventory]] - What hardware exists
|
|
- [[apps|ArgoCD Apps]] - What's deployed in Kubernetes
|
|
- [[routing|Routing]] - How services are exposed
|
|
|
|
## Credential Access
|
|
|
|
Credentials live in 1Password. Never retrieve them directly - use existing patterns:
|
|
- Ansible `pre_tasks` gather secrets at playbook start
|
|
- [[external-secrets]] syncs to Kubernetes
|
|
- Scripts use `op` CLI with user biometric prompts
|
|
|
|
## Common Pitfalls
|
|
|
|
| Pitfall | Correct Approach |
|
|
|---------|------------------|
|
|
| Missing kubectl context | Always add `--context=minikube-indri` |
|
|
| Deploying without review | Create PR first, wait for user approval |
|
|
| Re-explaining reference material | Link to reference cards instead |
|
|
| Committing to main without classifying | Classify as C0/C1/C2 first — only C0 goes to main |
|
|
| Guessing at credentials | Ask user or check 1Password patterns |
|