Erich Blume 50046f42f8 Add Phase 3 tutorials with audience targeting

Create tutorials directory with learning-oriented content:
- what-is-blumeops: High-level orientation (Reader, AI)
- exploring-the-docs: Navigation guide (All audiences)
- ai-assistance-guide: Context for AI assistance (AI, Owner)
- contributing: First contribution workflow (Contributor)
- replicating-blumeops: Overview for replicators

Add replication sub-tutorials:
- tailscale-setup: Networking foundation
- kubernetes-bootstrap: Cluster setup
- argocd-config: GitOps configuration
- observability-stack: Metrics, logs, dashboards

Each tutorial explicitly identifies target audiences and links
heavily to reference material rather than re-explaining.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-03 17:51:32 -08:00

3.1 KiB

Raw Blame History

title

AI Assistance Guide

Audiences: AI, Owner

This guide provides context for AI agents (like Claude Code) 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:

Always use --context=minikube-indri with kubectl - Work contexts exist that must never be touched
Run mise run zk-docs at session start - Review current infrastructure state
Never commit secrets - The repo is public at github.com/eblume/blumeops
Wait for user review before deploying - Create PRs, don't auto-deploy
Never merge PRs without explicit request - The user merges after review

Full rules are in the repo's CLAUDE.md.

Workflow Conventions

Feature Branches

All work happens on feature branches:

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:

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:

echo "Description" > docs/changelog.d/branch-name.feature.md

Types: feature, bugfix, infra, doc, misc

Service Locations

Understanding where services run helps target changes correctly:

Location	Services	Management
indri (native)	Forgejo, Zot, Jellyfin, Caddy	Ansible
[[cluster	Kubernetes]]	Everything else

Common Operations

Kubernetes Service Changes

Modify manifests in argocd/manifests/<service>/
Preview with argocd app diff <service>
Deploy with argocd app sync <service>

Indri Service Changes

Modify ansible role in ansible/roles/<service>/
Dry run: mise run provision-indri -- --check --diff --tags <service>
Deploy: mise run provision-indri -- --tags <service>

Health Checks

After changes:

mise run indri-services-check

For AI agents building context:

reference/index - Entry point for technical details
hosts - What hardware exists
apps - What's deployed in Kubernetes
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	Use feature branches
Guessing at credentials	Ask user or check 1Password patterns

3.1 KiB Raw Blame History