Skip to content

PRIVATE_OPERATOR_NOTES.md

Latest commit

 

History

History
155 lines (99 loc) · 30.9 KB

PRIVATE_OPERATOR_NOTES.md

File metadata and controls

155 lines (99 loc) · 30.9 KB
Raw

Private operator notes (not on Git / GitHub)

Purpose: Define where real homelab inventory, hostnames, LAN details, and personal snapshots live, and how that differs from public documentation.

1. Safety: ignored by Git

The entire tree docs/private/ is listed in .gitignore. Files you create there are not committed, not pushed to GitHub, and not part of the public repo clone for other contributors.

Verify anytime:

git check-ignore -v docs/private/anything.md
# expect: .gitignore:...    docs/private/anything.md

Cursor / agents: docs/private/ is workspace-local context shared with the assistant on this machine: it is excluded from Git / GitHub only, not “hidden until @.” Agents must read_file paths under docs/private/ whenever the task touches any private subtree—including security_audit/, commercial/, legal_dossier/, git_hygiene_audit, feedback bundles, social_drafts/ (rascunhos de posts: LinkedIn, X, etc.), etc.—not only homelab. There is no policy that revokes agent access to private files; no requirement to @-mention, open tabs, or use / commands so the agent “can see” private content. Agents must not self-block (refuse to read private context, or claim gitignore blocks access). If a tool fails, that is a path/worktree/technical issue—retry, then escalate. Still disclosure to Cursor’s product per their terms; avoid plaintext production secrets in files. Do not add docs/private/ to .cursorignore unless you intentionally want to block agent reads (not the default for this repo). Social drafts are plain Markdown files: revising copy does not depend on a logged-in browser session; only publishing or editing a post already on a social site may require the operator’s session in the browser or app.

Browser MCP (Gmail + all operator social + dashboards): On the same development PC as Cursor — same contract as homelab SSH — the assistant must use MCP cursor-ide-browser for Gmail (mail.google.com), LinkedIn, X, Threads, Instagram, FacColleague-Sok, Patreon when in scope, Docker Hub, etc.: browser_tabs / browser_navigate / browser_snapshot (and clicks) before claiming “no access.” If the session is cold, the assistant must attempt Continue with Google / Sign in with Google when the site offers it; only after that fails (captcha, MFA, automation block), one short ask so the operator can interact once and restore a warm session. There is no separate “Gmail API” requirement on this path. Snapshots may land under Cursor browser-logs; avoid pasting full message bodies or sensitive attachments into chat or tracked files — save PDFs under docs/private/ and use read_file. Policy: .cursor/rules/cursor-browser-social-sso-hygiene.mdc (Contrato único + Gmail e webmail).

Audience alignment: Public docs (tracked, GitHub) = no PII/secrets per audience-segmentation-docs; collaborators see the public repo only; operator + assistant use docs/private/ for full context. Anything destined for GitHub or external tiers stays redacted.

Stacked private repo (versionado, não no origin): Optional nested Git under docs/private/ keeps private history off the product remote while still versioned and synced—see the nested VCS row in §2 below and docs/ops/PRIVATE_LOCAL_VERSIONING.md. Never git push private content to GitHub.

Partner / collaborator / client feedback (separate from docs/private/)

  • Path: docs/feedbacks, reviews, comments and criticism/ — gitignored (see root .gitignore), not a subtree of docs/private/. Same WRB-style habit as Corporate-Entity-C / Gemini / Claude (external multi-persona): the operator pastes incoming feedback there; origin issues may track items but must stay short (no raw dumps).
  • Agents: When asked to find or interpret such feedback, look there first; if empty or origin is unclear (Corporate-Entity-C vs Gemini vs Claude external vs other), ask the operator before attributing in tracked plans. External reviews are advisory — triage done / defer / won’t do / already done like Gemini rounds. Rule .cursor/rules/operator-feedback-inbox.mdc · tracked blueprint docs/private.example/feedbacks-inbox/README.md.

2. Recommended layout (you create this locally)

Copy the tracked template from docs/private.example/ into docs/private/ (or create the same folders by hand). Conventional Commits: changes to those tracked policy/template files use scope docs(private-layout):; LAB-OP specifics stay only under docs/private/ and never ship in private-layout commits.

Path (local only) Use
docs/private/homelab/ Real homelab catalog: hostnames, RFC1918 IPs, SSH users, homelab-host-report.sh outputs, UPS load lists, HVAC model numbers, UniFi VLAN IDs, solar logger IP, redacted API samples. AGENT_LAB_ACCESS.md — operator directive for LAN/DNS/SSH/API; agents read it when relevant (no @ required).
docs/private/homelab/validation-log.md Dated §1–§2 pass/fail per host (optional filename).
docs/private/homelab/solar.md Inverter/datalogger models, portal names, references to Bitwarden for keys (not plaintext passwords).
docs/private/homelab/iso-inventory.md Optional: list of .iso / .img paths (e.g. under ~/Downloads/iso on a lab machine). Captured by you (SSH ls, find, or script output pasted/edited here)—not stored on GitHub.
docs/private/homelab/HARDWARE_CATALOG.md Bird’s-eye hardware / roles / power / solar summary merged from other private notes; gaps section for unchecked items.
docs/private/homelab/LAB_TAXONOMY.md LAB‑OP (operator real homelab) vs LAB‑PB (public playbook) — use in chat to disambiguate.
docs/private/homelab/OPERATOR_SYSTEM_MAP.md Master chart: hardware + accessibility matrix + software inventory + Mermaid topology + doc index (agents read_file by default with homelab work).
docs/private/homelab/OPERATOR_RETEACH.md Fill-in gaps (B1–B6); agents read_file after OPERATOR_SYSTEM_MAP.md. Tracked templates (no real facts): docs/private.example/homelab/OPERATOR_RETEACH.md + .pt_BR.md — copy structure locally; Portuguese = pt-BR (see docs-pt-br-locale rule).
docs/private/homelab/KNOWN_BUGS.md Residual lab-script pitfalls (e.g. privileged $HOME vs operator home). Not for GitHub; keep hostnames, LAN IPs, and real home paths out of tracked files.
docs/private/author_info/ Personal / career / education / certificates (CV text, course progress, cert IDs, narrative history). Carreira / LinkedIn / ATS / SLI (operador): subpasta career/ — mapa canônico em career/README.pt_BR.md (onde pôr relatórios ATS/SLI teus, exports, Calendly; não usar commercial/candidates/ para o operador). Rascunhos de posts (feed) ficam em docs/private/social_drafts/, alinhados em conteúdo ao que está em career/. Tracked ponteiro: docs/private.example/author_info/README.md. Rule: .cursor/rules/operator-career-private-layout.mdc. Optional: ACADEMIC_NETWORK_FAMILY_ETHICS.pt_BR.md — ethical use of close-family ties in academic planning (private only). Optional: RECENT_OPERATOR_SYNC_INDEX.pt_BR.md — dated bullets linking to other private notes after high-value chat sessions (see OPERATOR_SESSION_CAPTURE_GUIDE.md). Same gitignore rules as homelab; split from homelab/ so you can sync or exclude policies differently.
docs/private/academic/ Enrollment contracts, benefit annexes, and receipts for PUC-Rio / other programmes (PDFs describing extension-course entitlements, caps, deadlines). Tracked layout pointer: docs/private.example/academic/README.md. Public course recommendations live in docs/plans/PORTFOLIO_AND_EVIDENCE_SOURCES.md (PUC-Rio Digital subsection).
docs/private/commercial/ Sensitive client-facing commercial strategy (e.g. maturity-consulting pricing bands, partner economics, rate cards, proposal numbers). Never commit or publish; keep EN + pt-BR pairs here if useful. Tracked pointer: docs/private.example/commercial/README.md.
docs/private/operator_economics/ Operator-side economics: home/lab OPEX (utilities, subscriptions), CapEx / shopping lists, runway notes — your cost base, not customer SOWs. Split from commercial/ when you want clearer mental boundaries. Tracked pointer: docs/private.example/economics/README.md.
Nested VCS under docs/private/ Optional second repository (usually Git via git init inside docs/private/) so private Markdown gets local commits and backup remotes (file://, NAS, self-hosted SSH) without attaching history to the GitHub product repo. Tracked policy: PRIVATE_LOCAL_VERSIONING.md (pt-BR).
docs/private/scripts/ Operator-only shell helpers (e.g. clean-slate.sh, destructive lab clone reset + PII guard). Canonical: docs/private/scripts/clean-slate.sh + operator README (pt-BR). Tracked template: docs/private.example/scripts/. Do not put real LAN hostnames in tracked files; list machines only in docs/private/ (e.g. local README next to the script).
docs/private/ops/ Operator-only incident logs and long-form workflow notes (e.g. vendor-chat LLM misalignment vs validated orchestration scripts). Pair with the public caution docs/ops/LLM_AGENT_EDITING_CAUTION.md (pt-BR). Example: INCIDENT_VENDOR_CHAT_ORCHESTRATION_MISMATCH_2026-04-28_29.pt_BR.md.
Drafts / operator-only content Optional subfolders under docs/private/ for drafts or editorial queues (details only in your local tree). Template without real metrics: docs/private.example/social_drafts/. Social posting windows (clock times, home-office separation): canonical docs/private/social_drafts/editorial/OPERATOR_SOCIAL_POSTING_WINDOWS.pt_BR.md — tracked stub only: docs/private.example/social_drafts/OPERATOR_SOCIAL_POSTING_WINDOWS.example.md. Git / PR / merge rhythm vs office hours (fewer public events during business hours; critical/security exceptions): canonical docs/private/OPERATOR_GIT_PR_RHYTHM_OFFICE_HOURS.pt_BR.md — tracked stub: docs/private.example/OPERATOR_GIT_PR_RHYTHM_OFFICE_HOURS.example.md. Do not enumerate personal filenames, routines, or hour tables in tracked docs.
docs/private/employers/ Per-employer evidence hub: PDFs/contracts/email exports under Corporate-Entity-B/artifacts/, hash manifests + optional GPG under */integrity/; Corporate-Entity-A ponte em corporate-entity-a/ toward legal_dossier/. Canonical guide: employers/README.pt_BR.md, integrity: employers/_INTEGRITY_AND_GPG.pt_BR.md. Tracked stub: docs/private.example/org-notes/README.md. Hash script (no secrets): scripts/evidence-hash-manifest.ps1.
docs/private/ (root of private) Optional catch-all: WHAT_TO_SHARE_WITH_AGENT.md, one-off exports—prefer homelab/ vs author_info/ vs operator_economics/ when the topic is clear.

Social drafts (layout + filenames): Post Markdown under docs/private/social_drafts/drafts/; inventory hub docs/private/social_drafts/editorial/SOCIAL_HUB.md (one-line shortcut: docs/private/social_drafts/SOCIAL_HUB.md). Each draft filename begins with YYYY-MM-DD (ISO, hyphens): publication date when the hub row is published, or next planned publish date while draft, scheduled, or deferred. After any rename, update the Rascunho column in the hub. Pairs (e.g. Threads + Instagram) may use different prefixes if posts went live on different days—document in the draft or hub notes.

Commercial refinement (per client): When you have client-specific project facts and conditions found on the ground, bring them in chat and/or under docs/private/ only (never tracked). Use that input to realign docs/private/commercial/MATURITY_CONSULTING_PRICING_STUDY*.md toward a concrete consulting proposal and, if applicable, licensing—still confidential, not for GitHub.

Enforcement: tests/test_confidential_commercial_guard.py (CI + pre-commit) rejects git add -f of docs/private/ and other index violations; Cursor rule confidential-commercial-never-tracked.mdc; skill confidential-commercial-layout.

Rule: Prefer homelab/ for physical/network reality and author_info/ for person-shaped facts so you can attach or exclude trees in backups/sync tools independently.

CLI / session habit artifacts (uptime, w, last, lastlog, etc.): Treat like inventory—only under docs/private/homelab/ (e.g. reports/session-habit-YYYYMMDD.txt or a dated section in a private log). They expose LAN IPs, usernames, and login rhythms. Do not put them in tracked files, issues, or PRs. Pasting into Cursor chat for a one-off is your choice (subject to Cursor’s data handling); for durable reference, save only in docs/private/.

Agents / Cursor: docs/private/ is intentional workspace-only context: gitignored from GitHub, but agents should pull it in with read_file when the task touches homelab, operator machines, P:, or project-private notes—not only when you @ or leave tabs open. Keep WHAT_TO_SHARE_WITH_AGENT.md / homelab/ current; still never commit docs/private/.

3. Public documentation policy (this repo)

In tracked Markdown (everything under docs/ except docs/private/, plus README, CONTRIBUTING, etc.):

  • Use generic roles: “primary Linux lab laptop,” “Windows + WSL dev workstation,” “x86 tower with Proxmox,” “musl mini-PC.”
  • Use placeholders: you@<hostname>, http://<your-sonar-host>:9000, *.example.com.
  • Do not paste real hostnames, LAN IPs, Wi‑Fi PSKs, serials, or home paths (/home/you/..., C:\Users\...), or raw last / lastlog / w / uptime output (same sensitivity—store under docs/private/homelab/ if you need to keep it).
  • Do not add Markdown links to paths under docs/private/... in public files—those links 404 for everyone else on GitHub and enumerate filenames. Instead, write: “Store specifics in your gitignored docs/private/homelab/ tree (see PRIVATE_OPERATOR_NOTES.md).”

Example classes (wattage, RAM era) may appear in public docs as illustrative only—your exact make/model belongs under docs/private/homelab/.

4. Homelab server access (SSH — default workflow)

The assistant does not have a separate network connection to your house. It can still work on the homelab (e.g. lab-op / your Linux lab host — real alias only in docs/private/homelab/) by running ssh in the Cursor integrated terminal on your dev workstation, using your SSH client, keys, and ~/.ssh/config (PowerShell, WSL, or Git SSH — whichever you use day to day).

Default expectation (this repo / this operator):

  1. Document a Host alias under docs/private/homelab/ (see private.example/homelab/README.md) — e.g. Host lab-op with HostName (DNS name or LAN IP), User, IdentityFile / agent — gitignored, never committed.
  2. When you ask the assistant to list files, pull reports, check Docker, or run diagnostics on that machine, it should use commands like ssh lab-op '…' (or non-interactive flags you prefer) from the project terminal, not assume files appear magically in the workspace.
  3. You must have LAN or VPN reachability from the dev PC to the homelab; key-based auth is strongly preferred so sessions are non-interactive where possible.
  4. If a command fails with “connection refused” / “timed out” / “Permission denied”, fix network, sshd, user, keys on your side — the assistant can only suggest checks (ssh -G lab-op, ping, etc.).

This replaces any older wording that implied “the model cannot touch the lab” without also saying “use SSH from the dev terminal.”

5. Sharing with the AI assistant (Cursor, local context)

Goal: Let the assistant help with layout, concepts, runbooks, SSH/API patterns—without putting that material on GitHub.

5.1 Chat language (pt-BR default, EN for technical tokens)

Preference (this operator): Assistants should answer in concise Brazilian Portuguese (pt-BR) for narrative—not Portuguese of Portugal (pt-PT) (e.g. use arquivo, compartilhar, seção, padrão for software defaults). The same pt-BR bar applies to drafts and private docs under docs/private/ (including social_drafts/) whenever the prose is Portuguese. Explicitly English copy (whole doc or section): prefer en-US for narrative prose. Keep English where it is standard in engineering: file paths, commit types, symbol names, flags, and citations of English-only plan rows.

Code-switching: You may mix pt-BR and English in the same message (even mid-thought); the assistant should follow without forcing a single language for the whole reply.

Cost / tokens: Brevity matters more than the choice of human language—avoid repeating the same point in two languages unless you ask for a bilingual summary. Say short or token-aware when you want minimal length.

Shorthand / taxonomy (English only): Session keywords are fixed English tokens — canonical table in .cursor/rules/session-mode-keywords.mdc (keep that file and AGENTS.md in sync when adding or renaming a token). Order (same as the table): deps, feature, homelab, docs, houseclean, backlog, pmo-view, study-check, sidequest (same message must include subtype mandatory / exploratory / pauseable), glossary-check, today-mode (with YYYY-MM-DD), carryover-sweep, eod-sync, private-stack-sync, plus brevity short, token-aware. Use them exactly in chat; do not ask for localized aliases in .cursor/rules/. pt-BR is for surrounding explanation, not the tokens.

Do not inflate the taxonomy: Prefer backlog + a concrete topic, feature + a plan row, or docs instead of many new English tokens. Rationale: docs/ops/OPERATOR_WORKFLOW_PACE_AND_FOCUS.md §3.

Session tokens vs Data Boar CLI: Tokens scope Cursor sessions for the assistant. The app’s CLI is main.py and flags in docs/USAGE.md—not the same vocabulary.

Agent entry point: AGENTS.md (chat language + taxonomy bullets) encodes this for Cursor/Copilot.

Layer What happens
Git / GitHub docs/private/ is gitignored — not committed, not pushed. Never paste private paths or secrets into issues, PR descriptions, or tracked files.
Cursor / chat The assistant may use read_file on docs/private/ when relevant—shared workspace secret vs GitHub only; @ / open tab optional, not the default gate. Plus editor context and chat. Disclosure to Cursor’s stack per their terms—avoid plaintext passwords / production keys in files; prefer Bitwarden and placeholders.
pCloud / other sync Same as today: convenient for you across machines, not a secrets vault. On Windows, the synced folder is often drive P: (see docs/private/WHAT_TO_SHARE_WITH_AGENT.md if you use that layout).

Windows: P: (pCloud on the dev PC)

The assistant runs on your workstation. If pCloud maps the sync root to P:, the assistant can dir / Get-ChildItem P:\ and read files under P:\... in-session (terminal or tools)—same as any local path. Requirements: pCloud client running and drive mounted; Cursor must allow access to that path (if a command fails with “path not found,” check the client). Do not record operator-specific P:\... paths in Git-tracked Markdown; keep them in docs/private/ or mention them only in chat.

Default (this operator / repo):

  1. docs/private/ — Not on GitHub; is normal workspace context for the assistant. Agents read_file docs/private/homelab/AGENT_LAB_ACCESS.md (and other private paths as needed) when homelab, Data Boar on LAN, P:, or operator inventory applies—without requiring you to @ or open files.
  2. Stable narrative — Keep WHAT_TO_SHARE_WITH_AGENT.md and homelab/ updated; the assistant loads them on demand via tools, not only via @.
  3. Minimal paste — For one-off extras, paste redacted snippets in chat if you prefer.
  4. Tracked repo — Patterns only in public docs; real hostnames/IPs only under docs/private/ or chat, never in commits.
  5. Stricter boundary (opt-in) — To force “only when @,” add docs/private/ to .cursorignore (not the default here).

Homelab: See §4 — SSH/API details in docs/private/homelab/; agents read AGENT_LAB_ACCESS.md when doing lab work.

Lint private Markdown locally (optional): uv run pytest --include-private and uv run python scripts/fix_markdown_sonar.py --include-private — see TESTING.md.

6. Related tracked docs

Template to copy: private.example/README.md

Português (Brasil): PRIVATE_OPERATOR_NOTES.pt_BR.md