teleo-infrastructure/.agents/skills/teleo-leo-onboarding/SKILL.md

---
name: teleo-leo-onboarding
description: Use when a worker needs fast context on Teleo/Living IP, Leo architecture, VPS/GCP and Hermes runtime boundaries, database provenance, ingestion/apply/reconstruction, identity, testing, security, secrets, or incident recovery before doing Leo or Teleo work.
---

# Teleo / Leo Onboarding

## Job

Orient the worker before action. Build a current, proof-linked understanding of
the company/product, Leo's role, the infrastructure surfaces, and the exact
claim ceiling without rediscovering the system from historical chat.

## Trigger Phrases

- "onboard to Leo"
- "what is Teleo / Living IP"
- "load Leo VPS context"
- "Fable handoff for Leo"
- "before working on Teleo infra"
- "explain the architecture"
- "recover or reconstruct Leo"
- "which skill should I use"

## Core Model

- Teleo is the knowledge/agent infrastructure layer behind Leo.
- Leo is the operator-facing agent expected to answer in Telegram, remember operator context, reason from canonical KB state, stage concrete KB changes, and support approved changes becoming canonical DB rows with proof.
- The immediate July 9 issue is not generic bot liveness. It is m3taversal's expectation that approved KB changes move beyond proposal state when appropriate.
- The VPS is the currently proven Telegram-visible Leo surface.
- GCP is a separate lane. Direct passwordless SSH and `sudo -n` work as of
  2026-07-14. The newest VPS DB was restored to a disposable private Cloud SQL
  clone with exact parity, and a real ID-free no-send reasoning turn passed.
  The merged helper/skill were deployed, supported KB commands now fail closed
  to Cloud SQL, and the service survived a controlled restart with live
  post-restart status/search receipts. Persistent GCP `teleo_canonical` is still
  an older staging copy; Telegram delivery, GCP canonical mutation, ongoing
  replication, promotion, and cutover remain separate proof rows.

## Architecture Boundaries

- VPS canonical KB: Docker Postgres `teleo-pg`, database `teleo`.
- GCP canonical KB: private Cloud SQL database `teleo_canonical`.
- Canonical rows: `public.claims`, `public.sources`,
  `public.claim_evidence`, `public.claim_edges`, and related identity/strategy
  tables; staging/review is `kb_stage.*`.
- Hermes `state.db` and session JSONL files are conversation continuity, not
  canonical collective knowledge. GCP memory-sync success does not prove the
  canonical KB was restored or updated.
- `SOUL.md` is a rendered/runtime artifact. Direct file edits are not canonical
  identity changes without DB row and render/sync proof.

## Clean-Context First Commands

From the repository root, validate the pack without a virtual environment or
network access:

```bash
.agents/skills/teleo-leo-onboarding/scripts/validate_skill_pack.py --root .
```

Install exactly the manifest-indexed skills into an empty temporary agent skill
root with:

```bash
.agents/skills/teleo-leo-onboarding/scripts/install_skill_pack.py \
  --root . \
  --target /private/tmp/teleo-clean-agent/skills
```

Installed skills still resolve repository-relative routes against the current
`teleo-infrastructure` checkout. Keep the agent working directory at the repo
root. For pytest, use `.venv/bin/python`; if `.venv` is absent, create it from
`README.md` before running tests. Do not guess a bare `python` command.

Run the deterministic isolated acceptance canary with:

```bash
.agents/skills/teleo-leo-onboarding/scripts/run_clean_context_canary.py \
  --root . \
  --output docs/reports/leo-working-state-20260709/skill-pack-clean-context-canary-current.json
```

## Task Router

| Area | Skill | Canonical first route |
|---|---|---|
| Company, product, architecture | `teleo-leo-onboarding` | `docs/reports/leo-working-state-20260709/current-truth-index.md` |
| VPS runtime and incidents | `teleo-vps-runtime-ops` | Fresh service, deploy, DB, and cleanup readbacks |
| GCP and Cloud SQL | `teleo-gcp-parity-ops` | Current main evidence; keep open PR #148 candidate-only |
| Hermes packaging/runtime | `nousresearch-hermes-agent` | `hermes-agent/` plus the live service-specific ops skill |
| Database provenance | `teleo-infra-provenance` and `teleo-db-operator` | Separate Git, runtime, SQLite, Postgres, and retained proof |
| Source ingestion and proposal/apply | `teleo-kb-db-change-workflow` | Hash-bound source, review, guarded apply, receipt |
| Reconstruction and recovery | `teleo-reconstruction-recovery` | `docs/kb-rebuild-and-recompile.md` |
| Identity and rendered soul | `working-leo-m3taversal-outcomes` | Canonical identity rows before `SOUL.md` |
| Testing and proof tiers | `teleo-proof-handoff` | Exact tier, command, receipt, cleanup, claim ceiling |
| Secrets | `private-password-storage` | Provider login first; never paste or retrieve a secret |

## Read First

From the repo root, read:

1. `docs/reports/leo-working-state-20260709/current-truth-index.md`
2. `docs/reports/leo-working-state-20260709/gcp-db-first-working-leo-20260714.md`
3. `docs/reports/leo-working-state-20260709/gcp-db-first-parity-current.json`
4. `docs/reports/leo-working-state-20260709/gcp-db-first-blind-claim-current.json`
5. `docs/reports/leo-working-state-20260709/gcp-db-first-cleanup-current.json`
6. `docs/reports/leo-working-state-20260709/gcp-db-first-live-deploy-restart-current.json`
7. `docs/reports/leo-working-state-20260709/operator-surface-map.md`
8. `docs/reports/leo-working-state-20260709/working-leo-definition-20260709.md`
9. `.agents/skills/working-leo-m3taversal-outcomes/SKILL.md`
10. `docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.md`
11. `docs/reports/leo-working-state-20260709/gcp-cloud-sql-t3-live-readonly-current.md`
12. `docs/kb-rebuild-and-recompile.md`

## Required Status Split

Every status answer must split:

- `VPS runtime`
- `Telegram-visible Leo`
- `KB proposal/staging`
- `Canonical DB apply`
- `GCP parity`
- `Runtime/code provenance`

Do not collapse GCP demo readiness into Telegram completion. Do not collapse proposal approval into canonical DB application.

## Hard Boundaries

- Do not do paid route work or introduce paid-route naming.
- Do not change live VPS Leo runtime behavior unless explicitly authorized.
- Do not production-apply DB packets unless explicitly authorized.
- Do not expose secret contents.
- Do not treat an old summary as current if a fresh readback is cheap.
- PRs #146 and #147 are merged repository truth. PR #148 remains an open GCP
  least-privilege candidate until live `gh pr view 148` readback says otherwise;
  never route a deployment from its branch as though it were `main`.
- Use `ssh -o BatchMode=yes teleo-gcp-staging true` to preflight passwordless
  GCP VM access. If the firewall route drifts, rediscover the authenticated
  non-secret route before declaring a blocker. The OIDC/IAP workflow is still
  not bootstrapped. Do not print the Cloud SQL or Google password or create
  IAM/users inside a read-only lane.
- A benchmark score is not sufficient when an answer contradicts the DB receipt.
  Compare every printed count to `teleo-kb status` or the canonical manifest.

## Output Format

For onboarding handoffs, return:

1. Product/architecture summary in 8 bullets or fewer.
2. Current proof split by VPS, Telegram, DB, GCP.
3. Evidence files actually read.
4. Exact claim ceiling.
5. Next runnable non-production action.