Skip to content

Latest commit

 

History

History
143 lines (119 loc) · 38.5 KB

File metadata and controls

143 lines (119 loc) · 38.5 KB

Operator runbooks (docs/ops/)

This folder groups maintainer / operator procedural docs. Product usage docs (USAGE, TESTING, DOCKER_SETUP, etc.) stay under docs/ so app users are not sent through operator-only material.

Languages: Each runbook has an English file and a pt-BR twin (*.pt_BR.md). Plan history under docs/plans/ is English-only.

Before you open a PR (operators)

  1. From the repo root: Windows: .\scripts\check-all.ps1 (refreshes the plans dashboard, runs pre-commit, then full pytest). Linux / macOS: ./scripts/check-all.sh (same flow; PII gatekeeper_audit.py via uv — no pwsh required — #560). Thin twins: ./scripts/lint-only.sh, ./scripts/quick-test.sh, ./scripts/pre-commit-and-tests.sh — see SCRIPTS_CROSS_PLATFORM_PAIRING.md (pt-BR). Alternatively, run the same steps manually: python3 scripts/plans-stats.py --write (or python), uv run pre-commit run --all-files, uv run pytest -v -W error.
  2. Do not commit docs/private/ (real homelab inventory; gitignored) or git add -f config.yaml. Use the tracked template docs/private.example/ and policy PRIVATE_OPERATOR_NOTES.md.

Chat shorthand: pmo-view (plan / PMO docs, Markdown preview)

Token is English-only (same for all session keywords—see AGENTS.md and .cursor/rules/session-mode-keywords.mdc). Type pmo-view exactly; you can write the rest of the message in pt-BR.

In Cursor chat, say pmo-view when you want the assistant to surface plan and PMO-style docs and remind you how to read them rendered (tables, Gantt/Mermaid).

Defined in .cursor/rules/session-mode-keywords.mdc.


Today mode (one-day focus)

Dated checklists (OPERATOR_TODAY_MODE_YYYY-MM-DD.md), carryover queue, morning readiness ladder (Tier A daily; –1 / –1b / –1L cadence), and publish vs pyproject.toml sync live under today-mode/ — start there instead of hunting loose files in docs/ops/. Chat tokens: today-mode YYYY-MM-DD, carryover-sweep / morning-readiness (English-only). Social editorial + hub (private): today-mode/SOCIAL_PUBLISH_AND_TODAY_MODE.md (pt-BR); token social-today-check.


Index

Topic English Português (pt-BR)
SonarQube (home lab, Docker, CI / IDE / MCP) SONARQUBE_HOME_LAB.md SONARQUBE_HOME_LAB.pt_BR.md
Home lab — deploy smoke & data targets HOMELAB_VALIDATION.md HOMELAB_VALIDATION.pt_BR.md
QA with enforced licensing (60-day machine-bound .lic) QA_LOCAL_LICENSE.md QA_LOCAL_LICENSE.pt_BR.md
Lab vs host security (firewall, AppArmor, fail2ban, FIM, EDR) DATA_BOAR_LAB_SECURITY_TOOLING.md DATA_BOAR_LAB_SECURITY_TOOLING.pt_BR.md
Lab — external APIs / read-only DBs (no secrets in git) LAB_EXTERNAL_CONNECTIVITY_EVAL.md LAB_EXTERNAL_CONNECTIVITY_EVAL.pt_BR.md
Lab completão (runbook, multi-host smoke, contracts) LAB_COMPLETAO_RUNBOOK.md LAB_COMPLETAO_RUNBOOK.pt_BR.md
Lab-OP host personas (ENT / PRO / edge / bridge; Ansible + evidence) LAB_OP_HOST_PERSONAS.md LAB_OP_HOST_PERSONAS.pt_BR.md
Lab completão — brief for a fresh agent (copy-paste) LAB_COMPLETAO_FRESH_AGENT_BRIEF.md LAB_COMPLETAO_FRESH_AGENT_BRIEF.pt_BR.md
Completão — prompt library (completao + tier: + starter script) COMPLETAO_OPERATOR_PROMPT_LIBRARY.md COMPLETAO_OPERATOR_PROMPT_LIBRARY.pt_BR.md
Completão — prompt-mestre v1.7.3 (checklist SRE arquivado) COMPLETAO_MESTRE_RELEASE_CHECKLIST_PROMPT.md COMPLETAO_MESTRE_RELEASE_CHECKLIST_PROMPT.pt_BR.md
Maturity self-assessment POC (autonomous pytest + manual smoke) SMOKE_MATURITY_ASSESSMENT_POC.md SMOKE_MATURITY_ASSESSMENT_POC.pt_BR.md
WebAuthn JSON RP — pytest subset (Phase 1a) SMOKE_WEBAUTHN_JSON.md SMOKE_WEBAUTHN_JSON.pt_BR.md
Scope import — CSV quickstart (spreadsheet / memory, no CMDB yet) SCOPE_IMPORT_QUICKSTART.md SCOPE_IMPORT_QUICKSTART.pt_BR.md
Governance Lens (Pro) — GRC report + pandoc DOCX/PDF quickstart GOVERNANCE_LENS_QUICKSTART.md GOVERNANCE_LENS_QUICKSTART.pt_BR.md
Cursor — Markdown preview in-tab (no forced split) CURSOR_MARKDOWN_PREVIEW_SETTINGS.md CURSOR_MARKDOWN_PREVIEW_SETTINGS.pt_BR.md
Time Machine USB — recover now and repurpose safely TIME_MACHINE_USB_RECOVERY_AND_REPURPOSE.md TIME_MACHINE_USB_RECOVERY_AND_REPURPOSE.pt_BR.md
Talent dossier (talent-dossier next) + pool sync snapshot TALENT_DOSSIER_AND_POOL_SYNC.md TALENT_DOSSIER_AND_POOL_SYNC.pt_BR.md
LinkedIn + ATS playbook (SSI context, archetype keywords) LINKEDIN_ATS_PLAYBOOK.md LINKEDIN_ATS_PLAYBOOK.pt_BR.md
Lab-op — minimal container stack (Podman + k3s) LAB_OP_MINIMAL_CONTAINER_STACK.md LAB_OP_MINIMAL_CONTAINER_STACK.pt_BR.md
Lab-op firewall review baseline (public-safe) LAB_OP_FIREWALL_REVIEW_BASELINE.md LAB_OP_FIREWALL_REVIEW_BASELINE.pt_BR.md
ThinkPad LAB-NODE-01 + LMDE 7 — dev setup (apt, uv, segurança) LMDE7_LAB-NODE-01_DEVELOPER_SETUP.md LMDE7_LAB-NODE-01_DEVELOPER_SETUP.pt_BR.md
Windows WSL2 — Data Boar dev testing (second execution surface) WSL2_DATA_BOAR_DEV_TESTING.md WSL2_DATA_BOAR_DEV_TESTING.pt_BR.md
LAB-NODE-01 — baseline Ansible + sessão sudo / bw / VeraCrypt LAB-NODE-01_BASELINE_COMPLETION.md LAB-NODE-01_BASELINE_COMPLETION.pt_BR.md
Grafana Cloud — reactivation + first safe steps GRAFANA_CLOUD_REACTIVATION.md GRAFANA_CLOUD_REACTIVATION.pt_BR.md
Cloudflare GraphQL → OTLP edge metrics (#1599) CLOUDFLARE_GRAPHQL_OTLP_EXPORT.md CLOUDFLARE_GRAPHQL_OTLP_EXPORT.pt_BR.md
Grafana dashboard JSON exports (edge vs Faro) dashboards/README.md —
Pacotes, Topgrade, gta, Bitwarden CLI (bw) — workstation OPERATOR_PACKAGE_MAINTENANCE_AND_BW_CLI.md OPERATOR_PACKAGE_MAINTENANCE_AND_BW_CLI.pt_BR.md
Suggested full-day operator checklist (homelab + Band A) OPERATOR_NEXT_DAY_CHECKLIST.md OPERATOR_NEXT_DAY_CHECKLIST.pt_BR.md
Pace, focus, session tokens (Corporate-Entity-C + demo path) OPERATOR_WORKFLOW_PACE_AND_FOCUS.md OPERATOR_WORKFLOW_PACE_AND_FOCUS.pt_BR.md
Session keywords + LAB-OP SSH (lab-op) index OPERATOR_SESSION_SHORTHANDS.md OPERATOR_SESSION_SHORTHANDS.pt_BR.md
Cursor / agent policy map (Quick index — rules, skills, ops) CURSOR_AGENT_POLICY_HUB.md CURSOR_AGENT_POLICY_HUB.pt_BR.md
Cursor rules — phase 2 situationalization (Tier A/B/C, ritual) CURSOR_RULES_PHASE2_SITUATIONALIZATION.md CURSOR_RULES_PHASE2_SITUATIONALIZATION.pt_BR.md
Agent cold-start ladder (token-aware, fresh chat) OPERATOR_AGENT_COLD_START_LADDER.md OPERATOR_AGENT_COLD_START_LADDER.pt_BR.md
Token-aware scripts hub (map scripts to skills / keywords) TOKEN_AWARE_SCRIPTS_HUB.md TOKEN_AWARE_SCRIPTS_HUB.pt_BR.md
Scripts — Windows .ps1 ↔ Linux .sh pairing contract SCRIPTS_CROSS_PLATFORM_PAIRING.md SCRIPTS_CROSS_PLATFORM_PAIRING.pt_BR.md
PII public tree — operator guide (Parts I–III: cadence, remediation, fork vs clone; legacy paths are thin redirects) PII_PUBLIC_TREE_OPERATOR_GUIDE.md PII_PUBLIC_TREE_OPERATOR_GUIDE.pt_BR.md
PII remediation ritual (on-demand; private seeds; token-aware; session pii-remediation-ritual) PII_REMEDIATION_RITUAL.md PII_REMEDIATION_RITUAL.pt_BR.md
PII fresh-clone audit (Windows one-shot; pii-fresh-audit) PII_FRESH_CLONE_AUDIT.md PII_FRESH_CLONE_AUDIT.pt_BR.md
primary Windows dev PC workstation — no destructive repo ops on primary dev PC PRIMARY_WINDOWS_WORKSTATION_PROTECTION.md PRIMARY_WINDOWS_WORKSTATION_PROTECTION.pt_BR.md
Voidtools Everything (es.exe) on primary Windows dev PC — es-find token-aware EVERYTHING_ES_PRIMARY_WINDOWS_DEV_LAB.md EVERYTHING_ES_PRIMARY_WINDOWS_DEV_LAB.pt_BR.md
Commit conventions & PR hygiene COMMIT_AND_PR.md COMMIT_AND_PR.pt_BR.md
Branch protection on main (classic vs rulesets, required checks) BRANCH_PROTECTION.md BRANCH_PROTECTION.pt_BR.md
GitHub — canonical issue vs duplicate (gh issue close --duplicate-of) GITHUB_ISSUE_CANONICAL_AND_DUPLICATE_CLOSE.md GITHUB_ISSUE_CANONICAL_AND_DUPLICATE_CLOSE.pt_BR.md
Thin slices, priority bands, agent handoff (P0→P3) THIN_SLICE_AGENT_PRIORITY_HANDOFF.md THIN_SLICE_AGENT_PRIORITY_HANDOFF.pt_BR.md
Issue queue sequencing map (Mermaid — v1.8.0 / backlog / unassigned) ISSUE_QUEUE_SEQUENCING_MAP.md —
Native packages on GitHub Release (air-gap + SHA256SUMS) NATIVE_PACKAGE_RELEASE.md NATIVE_PACKAGE_RELEASE.pt_BR.md
Give-back: nfpm recipe for upstream podman-tui (#1424) GIVEBACK_PODMAN_TUI_NFPM.md GIVEBACK_PODMAN_TUI_NFPM.pt_BR.md
Homebrew tap (macOS, own tap, host Python, #1425) HOMEBREW_TAP.md HOMEBREW_TAP.pt_BR.md
Void xbps native overlay (Podman, runit, #1404) VOID_XBPS_PACKAGING.md VOID_XBPS_PACKAGING.pt_BR.md
Workflow follow-ups (branch protection, SBOM, deferred) WORKFLOW_DEFERRED_FOLLOWUPS.md WORKFLOW_DEFERRED_FOLLOWUPS.pt_BR.md
PyPI / TestPyPI PEP 740 attestation (live JSON/HTML; no badge) PYPI_PEP740_ATTESTATION_EVIDENCE.md PYPI_PEP740_ATTESTATION_EVIDENCE.pt_BR.md
Build provenance posture (Scorecard + GitHub Release attest; closes #1844) BUILD_PROVENANCE_POSTURE.md BUILD_PROVENANCE_POSTURE.pt_BR.md
Optional act + Podman workflow smoke (not in check-all; #1918) ACT_PODMAN_WORKFLOW_SMOKE.md ACT_PODMAN_WORKFLOW_SMOKE.pt_BR.md
WRB delta snapshot (paste block for next mail) WRB_DELTA_SNAPSHOT_2026-04-16.md WRB_DELTA_SNAPSHOT_2026-04-16.pt_BR.md
Today mode (index + carryover + publish sync) today-mode/README.md today-mode/README.pt_BR.md
Corporate-Entity-C — in-repo baseline paths (reviewers) Corporate-Entity-C_IN_REPO_BASELINE.md — (EN ops note; WRB template remains bilingual in Corporate-Entity-C_WRB_REVIEW_AND_SEND.pt_BR.md)
API key from environment (api_key_from_env) API_KEY_FROM_ENV_OPERATOR_STEPS.md — (EN-only; reduces ambiguity for operators and reviewers)
Credentials: env layer + vault-forward (*_from_env, XDG) OPERATOR_CREDENTIALS_FROM_ENV.md OPERATOR_CREDENTIALS_FROM_ENV.pt_BR.md
Operator secrets (Bitwarden) OPERATOR_SECRETS_BITWARDEN.md OPERATOR_SECRETS_BITWARDEN.pt_BR.md
Secure-by-default blockers + migration path SECURE_BY_DEFAULT_BLOCKERS_AND_MIGRATION.md SECURE_BY_DEFAULT_BLOCKERS_AND_MIGRATION.pt_BR.md
Secure dashboard (API key + HTTPS how-to) SECURE_DASHBOARD_AUTH_AND_HTTPS_HOWTO.md SECURE_DASHBOARD_AUTH_AND_HTTPS_HOWTO.pt_BR.md
Security inspiration review (GRC / Security Now) SECURITY_INSPIRATION_GRC_SECURITY_NOW.md SECURITY_INSPIRATION_GRC_SECURITY_NOW.pt_BR.md
Inspirations hub (navigation — start here) inspirations/INSPIRATIONS_HUB.md inspirations/INSPIRATIONS_HUB.pt_BR.md
Security/GRC inspiration baseline (multi-source) inspirations/README.md inspirations/README.pt_BR.md
Engineering craft inspirations (people, channels, narrative) inspirations/ENGINEERING_CRAFT_INSPIRATIONS.md inspirations/ENGINEERING_CRAFT_INSPIRATIONS.pt_BR.md
Gordon (Docker AI) workflow (token-aware, no secrets) GORDON_DOCKER_AI_USAGE.md GORDON_DOCKER_AI_USAGE.pt_BR.md
External LLM bundle (Gemini) — safe tracked-files export GEMINI_PUBLIC_BUNDLE_REVIEW.md GEMINI_PUBLIC_BUNDLE_REVIEW.pt_BR.md
LLM / agent editing caution (vendor chat vs validated scripts) LLM_AGENT_EDITING_CAUTION.md LLM_AGENT_EDITING_CAUTION.pt_BR.md
Recovery after manual doc cat / bundle mess DOC_BUNDLE_RECOVERY_PLAYBOOK.md DOC_BUNDLE_RECOVERY_PLAYBOOK.pt_BR.md
Remotes, origin, fork workflow REMOTES_AND_ORIGIN.md REMOTES_AND_ORIGIN.pt_BR.md
GitLab mirror of GitHub (read-only mirror) GITLAB_GITHUB_MIRROR.md GITLAB_GITHUB_MIRROR.pt_BR.md
Branch + Docker cleanup (legacy remote §7) BRANCH_AND_DOCKER_CLEANUP.md BRANCH_AND_DOCKER_CLEANUP.pt_BR.md
Docker image release order + Hub description (copy/paste) DOCKER_IMAGE_RELEASE_ORDER.md DOCKER_HUB_REPOSITORY_DESCRIPTION.pt_BR.md (ponteiro)
Operator notification channels OPERATOR_NOTIFICATION_CHANNELS.md OPERATOR_NOTIFICATION_CHANNELS.pt_BR.md
Chat → durable notes (session capture policy) OPERATOR_SESSION_CAPTURE_GUIDE.md OPERATOR_SESSION_CAPTURE_GUIDE.pt_BR.md
Private tree — local Git / VCS (never GitHub) PRIVATE_LOCAL_VERSIONING.md PRIVATE_LOCAL_VERSIONING.pt_BR.md
Operator / IT minimal permissions OPERATOR_IT_REQUIREMENTS.md OPERATOR_IT_REQUIREMENTS.pt_BR.md
Aggregated-identification practical tuning (Phase C) AGGREGATED_IDENTIFICATION_TUNING.md AGGREGATED_IDENTIFICATION_TUNING.pt_BR.md
Troubleshooting Docker deployment TROUBLESHOOTING_DOCKER_DEPLOYMENT.md TROUBLESHOOTING_DOCKER_DEPLOYMENT.pt_BR.md
Cursor on Ubuntu / Zorin + AppArmor CURSOR_UBUNTU_APPARMOR.md CURSOR_UBUNTU_APPARMOR.pt_BR.md

Related (not in this folder): SECURITY.md / SECURITY.pt_BR.md and CODE_PROTECTION_OPERATOR_PLAYBOOK.md / CODE_PROTECTION_OPERATOR_PLAYBOOK.pt_BR.md — security posture and Priority band A hardening next to the main security policy in docs/README.md.

Optional helper scripts (repo scripts/)

Script Purpose
poll_dashboard_scan.py POST /scan, poll /status until idle, print a report download hint. Set DATA_BOAR_BASE or --base; optional DATA_BOAR_API_KEY / --api-key when require_api_key is on; --interval / --max-polls to tune waits. Run uv run python scripts/poll_dashboard_scan.py --help. Per AGENTS.md, do not commit hostnames or keys—use env or docs/private/ only.
snmp-LAB-ROUTER-01-lab-probe.ps1 / snmp-LAB-ROUTER-01-lab-probe-to-log.ps1 / snmp-lab-ifwalk.sh SNMPv3 IF-MIB walk; -EnvFile per device; snmp-lab-ifwalk.sh on Linux lab-op. Targets + v2c notes: SNMP_LAB_TARGETS.md (pt-BR); Task Scheduler: private.example/homelab/reports/README.md § SNMP.
git-progress-recap.ps1 Token-aware pace check: groups recent origin/main commits by date (default 3 days; -Days 7, -MaxPerDay, -NoFetch). See OPERATOR_WORKFLOW_PACE_AND_FOCUS.md §8 (pt-BR). Pairs with today-mode, carryover-sweep, eod-sync — not a replacement for PLANS_TODO.md.
smoke-maturity-assessment-poc.ps1 Fast pytest subset for the maturity self-assessment POC (gate 1 of SMOKE_MATURITY_ASSESSMENT_POC.md). Does not replace check-all before merge.

Link-audit checklist (after moving or renaming docs)

Use this when opening a PR such as docs: cluster ops runbooks under docs/ops.

  • README.md / README.pt_BR.md — tables and bullets under Internal and reference / Ops.
  • Root CONTRIBUTING.md — any docs/… paths touched by the move.
  • .cursor/rules/ and .cursor/skills/ — deep links into docs/ or docs/ops/.
  • Cross-doc links inside moved files (../, ops/, plans/).
  • docs/plans/*.md — relative links from plans/ to ../ops/… or ../CODE_PROTECTION….
  • Optional: rg for the old path (e.g. docs/HOMELAB_VALIDATION.md without ops/) and fix stragglers.

Do not change .github/ workflows, sonar.sources, or relocate root SECURITY / CONTRIBUTING unless the goal is explicitly to do so; prefer link updates only.

Automation: uv run pytest tests/test_docs_markdown.py tests/test_markdown_lint.py