# ByteLyst AI Operating System Adoption Roadmap

> **Status:** Proposed adoption roadmap
> **Owner:** ByteLyst / Saravana
> **Created:** 2026-05-29
> **Source prompt:** Review Nate Herk's “I Turned Claude Opus 4.8 Into My Entire AI Operating System” and recommend how ByteLyst should adopt the pattern.
> **Primary target repo:** `learning_ai_common_plat`
> **Related docs:** [`docs/ecosystem/`](./), [`docs/MCP+A2A/`](../MCP+A2A/README.md), [`docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md`](./ECOSYSTEM_AGENT_OPERATING_MODEL.md)

---

## Executive Recommendation

ByteLyst should adopt the **AI Operating System (AIOS)** pattern, but not as a wholesale clone of a Claude Code starter kit. ByteLyst already has stronger primitives than the starter kit assumes: Hermes persistent memory, skills, cron jobs, Telegram delivery, a common platform repo, MCP/A2A docs, platform services, telemetry, kill-switch packages, and cross-repo delegation workflows.

The recommended move is to convert ByteLyst's existing agent ecosystem into a disciplined **ByteLyst AIOS operating layer** using four layers:

1. **Context** — durable company, product, decision, repo, and operator knowledge.
2. **Connections** — live read/write access to the tools and data that run ByteLyst.
3. **Capabilities** — reusable skills, scripts, MCP tools, agents, and playbooks that produce business artifacts.
4. **Cadence** — scheduled or event-driven routines that run without being prompted, with Telegram review and approval gates.

This aligns directly with ByteLyst's current direction: common platform, agent runtime contract, ecosystem adoption docs, delegation packs, persistent Hermes operations, Gitea/GitHub workflows, and product-agnostic services.

**Bottom line:** treat Hermes + `learning_ai_common_plat` + ByteLyst repos as the operating system, not just as tooling. Claude Code/AIS-OS is useful as a reference pattern, but the ByteLyst implementation should be **Hermes-native, repo-backed, audit-friendly, and production-safe**.

---

## Research Notes And Grounding

### Video / External Source

- YouTube video: <https://youtu.be/0WDkwMxj13s>
- oEmbed title: **“I Turned Claude Opus 4.8 Into My Entire AI Operating System”**
- Author: **Nate Herk | AI Automation**
- Related public starter kit: <https://github.com/nateherkai/AIS-OS>
- Related public post summaries mention:
  - Four C's: **Context, Connections, Capabilities, Cadence**
  - Three M's: **Mindset, Method, Machine**
  - “Bike Method” for safely increasing autonomy
  - Claude Code as the default working surface
  - Files, skills, and recurring rituals as the backbone of the system

### Transcript Retrieval Status

The YouTube transcript could not be fetched from this VM because YouTube blocked the request as bot/cloud traffic. Fallback attempts performed:

1. `youtube-transcript-api` via the local `youtube-content` helper.
2. YouTube oEmbed metadata extraction.
3. `yt-dlp` subtitle extraction.
4. Web search and extraction of related public materials.
5. Direct clone and inspection of the public `nateherkai/AIS-OS` repository.

This roadmap is therefore grounded in accessible metadata, public post summaries, the related MIT-licensed starter repository, and ByteLyst repo inspection. It avoids claiming direct transcript quotes from the unavailable video.

---

## What The AIOS Pattern Is

An AIOS is not “one big agent.” It is a managed operating layer that combines persistent context, tool access, reusable capabilities, and recurring execution.

The practical litmus test from the AIS-OS starter kit is:

> While you are not at your desk, the AIOS observes one real-world event and produces an output that is faster and more accurate than what you would produce yourself.

For ByteLyst, translate that into:

> While Saravana is offline, ByteLyst AIOS detects a meaningful operational event, gathers the right repo/product/system context, produces a correct artifact or recommendation, and routes it through the right Telegram / git / approval path with audit evidence.

Examples:

- A Gitea runner fails a deployment and Hermes produces a root-cause brief plus suggested patch scope.
- A nightly platform health check detects a regression and opens or updates a tracker item.
- A weekly ecosystem audit summarizes cross-repo drift, stale docs, broken assumptions, and top leverage tasks.
- A new app repo is created and the AIOS generates adoption docs, platform integration checklist, telemetry plan, and Docker/Gitea setup tasks.

---

## Why ByteLyst Should Adopt It

### 1. ByteLyst Is A Single-Developer Company

A single developer needs leverage more than process theater. The AIOS pattern is valuable because it compresses roles:

- platform architect
- devops operator
- QA reviewer
- documentation maintainer
- product analyst
- support triage assistant
- release coordinator
- security reviewer

The goal is not to remove Saravana from decisions. The goal is to make every decision arrive with context, options, evidence, and a recommended next action.

### 2. Existing ByteLyst Assets Already Map To AIOS Layers

ByteLyst already has much of the infrastructure:

- Hermes skills: reusable procedure layer.
- Hermes cron jobs: cadence layer.
- Telegram integration: operator interface and approval channel.
- `learning_ai_common_plat`: common contracts, packages, SDKs, services, platform-service, mcp-server, monitoring.
- Ecosystem docs: shared schemas, event taxonomy, runtime contract, adoption plans.
- Gitea/GitHub remotes: execution and audit trail.
- Docker/Caddy/systemd: production runtime surface.
- Persistent memories and session search: recall surface.

Adoption should therefore focus on **normalizing and governing what exists**, not rebuilding from zero.

### 3. It Converts One-Off Agent Work Into A Compounding System

Current agent work can become fragmented: useful fixes, docs, and scripts exist, but value depends on remembering where they are and when to run them. AIOS adoption makes them compounding:

- Every repeated task becomes a skill, script, or checklist.
- Every operational decision lands in a decisions log or ecosystem tracker.
- Every integration is registered in a connections registry.
- Every autonomous routine has an owner, trigger, output, risk level, and kill switch.

### 4. It Creates A Productizable Pattern

ByteLyst can later turn this into client-facing or product-facing capability:

- “AIOS for solo operators”
- managed AI operations layer for small businesses
- app-specific AI copilots built on ByteLyst platform services
- marketplace-ready agent capabilities using existing MCP/A2A docs

But first, dogfood internally.

---

## What Not To Do

Do **not** adopt the hype version of AIOS:

- Do not give agents broad write access before read-only audit value is proven.
- Do not build one giant autonomous agent.
- Do not automate waste. Eliminate first.
- Do not hide behavior in opaque prompts with no audit trail.
- Do not store secrets in repo context files.
- Do not make Claude Code the only surface. ByteLyst already uses Hermes, Telegram, cron, Gitea, and platform services.
- Do not expose the Hermes dashboard publicly.
- Do not ship L4 autonomy for production actions until lower levels have produced clean evidence.

The adoption principle should be: **boring, observable, reversible automation**.

---

## Framework Mapping: AIS-OS → ByteLyst AIOS

### Four C's Mapping

| AIS-OS Layer | ByteLyst Interpretation                                                | Current Assets                                                                         | Gaps To Close                                                                 |
| ------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Context      | Business, product, repo, ops, decisions, preferences, incident history | Hermes memory, session search, ecosystem docs, adoption docs, repo READMEs             | Consolidated AIOS context pack, decisions log discipline, source-of-truth map |
| Connections  | Tools/data Hermes can read/write safely                                | Git/Gitea/GitHub, filesystem, Google Drive, Telegram, services, Docker, systemd, Caddy | Formal connection registry, auth status, read/write scope, freshness checks   |
| Capabilities | Skills, scripts, MCP tools, workflows, agents                          | 100+ Hermes skills, common platform packages, MCP server docs, devops scripts          | Capability catalog, KPI mapping, owner/risk/autonomy metadata                 |
| Cadence      | Scheduled/event-driven routines                                        | Hermes cron, Telegram updates, backup cron, monitoring                                 | Routine registry, SLAs, output contracts, escalation rules, kill switches     |

### Three M's Mapping

| Three M | ByteLyst Adoption                                                                  | Practical Rule                                                                        |
| ------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Mindset | Default-shift every repeated task into an AIOS candidate                           | Ask: “To what extent can Hermes handle this next time?”                               |
| Method  | Find constraint → eliminate/automate/delegate → map process → autonomy level → KPI | No new automation without trigger, data, decision point, destination, KPI             |
| Machine | Lego blocks, validation chain, Bike Method, intern rule, kill switch               | Small scripts/skills first, read-only first, phase autonomy upward only with evidence |

---

## Recommended ByteLyst AIOS Architecture

```text
ByteLyst AIOS
├── Operator Surface
│   ├── Telegram DM updates and approvals
│   ├── Hermes chat/session tools
│   └── Git commits/PRs/issues for durable work
├── Context Layer
│   ├── Hermes user profile + durable memories
│   ├── session_search for historical decisions
│   ├── learning_ai_common_plat/docs/ecosystem
│   ├── adoption docs per product repo
│   └── decisions / incident / run logs
├── Connections Layer
│   ├── GitHub + local Gitea
│   ├── Google Drive folder hemes_files
│   ├── Telegram gateway
│   ├── Docker/systemd/Caddy
│   ├── platform-service / mcp-server / extraction-service
│   └── future: email, calendar, Linear/Notion, finance, customer data
├── Capabilities Layer
│   ├── Hermes skills
│   ├── repo scripts
│   ├── MCP tools
│   ├── cron-backed workflows
│   ├── subagent delegation workflows
│   └── product-specific operational playbooks
└── Cadence Layer
    ├── daily/weekly/monthly cron jobs
    ├── event-driven webhook subscriptions
    ├── CI/deploy/monitoring triggers
    ├── Telegram escalation policies
    └── kill-switch + pause/resume controls
```

---

## Proposed Repository Layout Additions

Add a dedicated AIOS folder under the existing ecosystem docs:

```text
docs/ecosystem/aios/
├── README.md                         # AIOS overview and source-of-truth map
├── CONTEXT_PACK.md                   # ByteLyst business/product/operator context index
├── CONNECTIONS_REGISTRY.md           # tool/data/API/system registry
├── CAPABILITY_CATALOG.md             # skills/scripts/MCP/cron capabilities
├── CADENCE_REGISTRY.md               # recurring routines and schedules
├── AUTONOMY_POLICY.md                # L0-L4 policy, Bike Method, approval gates
├── AUDIT_SCORECARD.md                # Four C's recurring audit template/results
├── DECISIONS_LOG.md                  # AIOS-specific decisions if not merged into tracker
└── ROADMAP.md                        # adoption execution tracker
```

Do not move all existing docs immediately. Start with index files that point to existing source-of-truth docs. Consolidate only after patterns stabilize.

---

## Autonomy Policy For ByteLyst

Use five levels:

| Level | Name       | Allowed Behavior                                          | ByteLyst Default                                                        |
| ----- | ---------- | --------------------------------------------------------- | ----------------------------------------------------------------------- |
| L0    | Manual     | AI only explains or documents                             | Rare, for high-risk operations                                          |
| L1    | Suggested  | AI recommends; Saravana executes                          | Default for new production changes                                      |
| L2    | Drafted    | AI drafts artifact/patch; human reviews before use        | Default for docs, plans, issue drafts, config suggestions               |
| L3    | Supervised | AI executes within scoped boundaries and reports evidence | Allowed for docs commits, read-only audits, safe repo tasks             |
| L4    | Autonomous | AI executes end-to-end without per-run approval           | Only for low-risk recurring routines with kill switch and clean history |

### Initial L4 Candidates

Only low-risk, reversible tasks should be L4 early:

- sanitized backup sync status checks
- read-only repo/document freshness audits
- health summaries that do not mutate production
- weekly capability catalog drift report

### L4 Explicitly Not Allowed Initially

- production deploys
- secret rotation
- public DNS/Caddy exposure changes
- database migrations
- billing/payment actions
- user deletion or account changes
- emails/messages sent externally as Saravana
- force-pushes or destructive git operations

---

## Bike Method Rollout For ByteLyst

### Phase 1 — Training Wheels

- Run manually from Hermes chat.
- Agent reads context and drafts outputs.
- Saravana or Hermes operator reviews every output.
- No scheduled mutation.

Use for:

- first AIOS audit
- first connection registry
- first capability catalog
- first weekly executive brief

### Phase 2 — Guided

- Cron or webhook triggers draft output.
- Output goes to Telegram for approval.
- Agent does not write to production systems without explicit approval.

Use for:

- weekly repo drift brief
- pending CI/deploy recommendations
- docs freshness queue
- daily “what needs attention” brief

### Phase 3 — Watched

- Agent performs safe scoped actions.
- Telegram receives summary and evidence.
- Failures escalate immediately.
- Periodic batch review checks quality.

Use for:

- docs-only commits on dedicated branches
- issue creation with labels
- PR status monitoring
- stale cron/job checks

### Phase 4 — Hands-Off

- Agent executes end-to-end.
- Metrics and logs prove quality.
- Kill switch exists.
- Scope remains narrow and reversible.

Use only after 2-4 weeks of clean Phase 3 evidence.

---

## Priority Capabilities To Build First

### Capability 1: Weekly ByteLyst AIOS Audit

**Why:** Establishes the baseline score and prevents the system from becoming messy.

**Inputs:**

- Hermes skills list
- Hermes cron list
- repo docs under `docs/ecosystem/`
- git status across active repos
- recent decisions / session search
- connection registry

**Output:**

- Four C's score: Context, Connections, Capabilities, Cadence
- top 3 gaps ranked by leverage
- one recommended action for the week
- Telegram summary
- committed audit report in `docs/ecosystem/aios/audits/`

**Autonomy:** Start L2, move to L3 after two clean runs.

**KPI:** Reduce unknown/stale operating assumptions; target a score above 80/100 by the end of Phase 2.

---

### Capability 2: Connection Registry And Freshness Checker

**Why:** Agents are only useful if they know what they can safely access.

**Registry fields:**

- connection name
- domain: git, docs, messaging, infra, cloud, finance, customer, calendar, email, product service
- mechanism: API, CLI, MCP, script, file, webhook
- auth location: never raw secret, only env/template reference
- read/write scope
- owner
- last verified timestamp
- verification command
- failure mode
- autonomy ceiling

**Initial connections to include:**

- Telegram home channel
- GitHub remotes
- local Gitea remotes
- Google Drive `hemes_files`
- Docker
- systemd
- Caddy
- Hermes cron
- Hermes skills
- `platform-service`
- `mcp-server`
- `extraction-service`
- FreeLLMAPI
- MarkItDown

**Autonomy:** L1/L2 for registry edits, L3 for read-only freshness checks.

**KPI:** 100% of production-affecting connections documented with verification commands.

---

### Capability 3: Capability Catalog

**Why:** ByteLyst already has many reusable skills and scripts, but they need a discoverable operating catalog.

**Catalog fields:**

- capability name
- trigger phrase or cron job
- input requirements
- output artifact
- repos/files touched
- verification command
- required secrets/connections
- autonomy level
- risk level
- owner
- kill switch
- last successful run

**Initial catalog sections:**

- Devops operations
- Git/Gitea/GitHub workflows
- Documentation and roadmap generation
- YouTube/content research
- Google Drive uploads
- Backup operations
- MCP/A2A orchestration
- Product adoption docs
- CI/deploy troubleshooting

**Autonomy:** L2 for catalog creation; L3 for periodic stale-capability reports.

**KPI:** Any repeated ByteLyst task can be found by name and reused without rediscovery.

---

### Capability 4: Daily / Weekly Operator Brief

**Why:** Reduces tab switching and makes Hermes the default operating surface.

**Daily brief inputs:**

- git dirty/ahead status for active repos
- failing services or health checks
- cron job failures
- high-priority reminders from previous sessions
- active roadmap docs
- Gitea/GitHub branches needing push/merge

**Weekly brief inputs:**

- completed commits by repo
- open blockers
- stale adoption docs
- top leverage automation candidate
- connection freshness
- capability catalog drift

**Output:** Telegram message with action-first ordering.

**Autonomy:** L2 initially. L3 once false positives are low.

**KPI:** Fewer manual status checks; one place to decide what to do next.

---

### Capability 5: Agent Work Intake And Routing

**Why:** User already wants continuous agent execution with commits/pushes and progress updates. Standardize the intake.

**Inputs:** user request, repo map, current git state, available skills, risk level.

**Routing rules:**

- Use Hermes directly for cross-repo architecture, production ops, security, and final integration.
- Use subagents for bounded research/review tasks.
- Use Claude Code/Codex/OpenCode only when a coding task is large enough to justify a separate agent runtime.
- Use cron jobs for durable repeated monitoring.
- Use docs/plans for complex roadmap-driven work.

**Output:** task plan, execution boundaries, verification commands, progress update policy, commit strategy.

**Autonomy:** L2/L3 depending on repo risk.

**KPI:** Less ambiguity before coding; fewer half-finished agent runs.

---

### Capability 6: Production-Safe Change Gate

**Why:** ByteLyst runs real services on one VM. Agents need clear guardrails.

**Gate checklist:**

- Does this expose a private dashboard or service publicly?
- Does this touch secrets, auth, DNS, Caddy, Docker Compose, systemd, database, or billing?
- Is there a rollback command?
- Is there a health check?
- Is there a git diff and commit message?
- Is the target remote correct: GitHub vs local Gitea?
- Does the action need Telegram approval?

**Autonomy:** L1 for high-risk, L2 for medium-risk, L3 for docs-only/safe actions.

**KPI:** Zero unreviewed production-affecting changes.

---

## Roadmap

### Phase 0 — Baseline And Guardrails (1-2 days)

**Goal:** Create the AIOS source-of-truth docs and audit baseline.

Tasks:

- Create `docs/ecosystem/aios/README.md`.
- Create `CONTEXT_PACK.md` as an index, not a secret dump.
- Create `CONNECTIONS_REGISTRY.md` with known connections and verification commands.
- Create `CAPABILITY_CATALOG.md` with current Hermes skills/scripts/cron categories.
- Create `AUTONOMY_POLICY.md` with L0-L4 rules and Bike Method rollout.
- Create `AUDIT_SCORECARD.md` with first Four C's score.
- Add links from `docs/ecosystem/README.md`.

Exit criteria:

- AIOS docs exist and link to current ecosystem docs.
- No secrets are committed.
- At least 10 core connections are documented.
- At least 20 capabilities or capability families are cataloged.

---

### Phase 1 — Context Consolidation (3-5 days)

**Goal:** Make fresh agent sessions understand ByteLyst without rediscovery.

Tasks:

- Build a ByteLyst context pack:
  - company overview
  - active repos
  - production VM map
  - product list
  - platform architecture links
  - deployment constraints
  - user preferences and communication rules
- Normalize decisions logging:
  - link ecosystem tracker, adoption docs, and AIOS decisions
  - define what belongs in repo docs vs Hermes memory
- Add “source of truth hierarchy” for AIOS work.
- Document which facts must never be stored in memory or repo docs.

Exit criteria:

- New agent can answer “what does ByteLyst run and where?” from docs.
- New agent can identify safe vs high-risk actions.
- Decision logging location is unambiguous.

---

### Phase 2 — Connections And Read-Only Observability (1 week)

**Goal:** Make the AIOS see current system state reliably.

Tasks:

- Add verification commands for:
  - git status across active repos
  - Docker containers
  - systemd services
  - Caddy config check
  - Hermes cron list
  - Hermes skills list
  - platform service health endpoints
  - Gitea runner status
- Add read-only scripts where needed.
- Create a weekly connection freshness report.
- Start Telegram-delivered read-only status brief.

Exit criteria:

- AIOS can produce current operational state without manual paste.
- Broken/expired connections are surfaced as blockers.
- All read-only checks are safe to run from cron.

---

### Phase 3 — Capability Productization (1-2 weeks)

**Goal:** Turn repeated work into durable, reusable capabilities.

Tasks:

- Pick top 5 repeated workflows from recent Hermes work.
- For each workflow:
  - write or update a skill
  - add verification steps
  - add rollback or kill-switch notes
  - add catalog entry
  - assign autonomy level
- Prioritize:
  - Gitea/GitHub workflow operations
  - Caddy subdomain routing
  - Hermes backup operations
  - YouTube/content-to-roadmap research
  - platform docs/adoption updates

Exit criteria:

- Repeated tasks no longer require re-explaining.
- Capability catalog points to exact skills/scripts/docs.
- At least five capabilities have run successfully from the catalog.

---

### Phase 4 — Cadence And Routines (1-2 weeks)

**Goal:** Move from reactive usage to operating rhythm.

Tasks:

- Create or refine cron jobs for:
  - daily operator brief
  - weekly AIOS audit
  - connection freshness check
  - stale repo/docs drift check
  - backup status report
- Ensure every routine has:
  - owner
  - schedule
  - output target
  - failure alert
  - kill switch
  - autonomy level
- Add Telegram summary format with action-first bullets.

Exit criteria:

- Routines run without prompting.
- Failures are visible.
- No routine mutates production without policy clearance.

---

### Phase 5 — Safe Supervised Execution (2-4 weeks)

**Goal:** Let AIOS execute narrow, reversible tasks with evidence.

Candidate tasks:

- docs-only branch creation and commit
- stale link fixes
- issue/roadmap draft creation
- read-only audit report commits
- PR check monitoring
- dependency freshness reports

Requirements:

- dedicated branches for mutation
- no force pushes
- commit messages follow conventional commits
- Telegram notification includes files changed and verification
- production changes remain L1/L2

Exit criteria:

- At least three L3 routines complete successfully.
- Rollback path is documented.
- Saravana trusts the summaries without reopening every file.

---

### Phase 6 — Productize For ByteLyst Offerings (Later)

**Goal:** Convert internal AIOS dogfood into product/client patterns.

Possible offerings:

- AIOS starter kit for solo operators
- managed automation OS for small businesses
- product-specific copilots for ByteLyst apps
- AI readiness audit based on Four C's-style scoring
- marketplace-ready AI capabilities using `mcp-server` and platform-service

Do not start here. Productize only after internal routines prove valuable.

---

## Recommended First 10 Implementation Tickets

1. **Create AIOS docs folder** under `docs/ecosystem/aios/` with README and source-of-truth map.
2. **Draft AIOS autonomy policy** with L0-L4, Bike Method phases, approval gates, kill switches.
3. **Create connection registry** for Telegram, GitHub, Gitea, Docker, systemd, Caddy, Google Drive, Hermes cron, Hermes skills, platform services.
4. **Create capability catalog** from current Hermes skills, known scripts, and common platform MCP/A2A docs.
5. **Create first AIOS audit scorecard** and record baseline Four C's score.
6. **Add a weekly AIOS audit cron** that produces a Telegram summary and optionally commits report after review.
7. **Add daily operator brief prototype** as L2 Telegram-only draft.
8. **Write production-safe change gate checklist** and link it from `AGENTS.md` or ecosystem operating model.
9. **Convert top repeated workflow into a ByteLyst skill**: YouTube/content research → roadmap doc → commit/push.
10. **Review after two weeks** and promote only the cleanest read-only routines from L2 to L3.

---

## Suggested Four C's Baseline For ByteLyst Today

This is a qualitative initial estimate based on repo/system inspection, not a formal audit.

| Layer        |   Estimate | Rationale                                                                                               |
| ------------ | ---------: | ------------------------------------------------------------------------------------------------------- |
| Context      |      18/25 | Strong ecosystem docs and Hermes memory, but AIOS-specific source-of-truth map is missing.              |
| Connections  |      16/25 | Many live connections exist, but no formal registry with auth/freshness/read-write scope.               |
| Capabilities |      21/25 | Hermes skills and repo scripts are strong; catalog and KPI mapping are missing.                         |
| Cadence      |      17/25 | Cron exists and Telegram works; routine registry, output contracts, and autonomy policy are incomplete. |
| **Total**    | **72/100** | ByteLyst is already in “built/early compounding” territory. Main gap is governance and cataloging.      |

Target after Phase 4: **85+/100**.

---

## Governance Recommendations

### Source-Of-Truth Rules

- Repo docs are source of truth for architecture, policies, and durable operating contracts.
- Hermes memory stores compact durable preferences/environment facts only.
- Session history is used for recall, not as canonical documentation.
- Secrets stay in env files, secret stores, or existing deployment mechanisms, never in AIOS docs.
- Connection registry may name env var keys but must not include values.

### Commit Rules

- Docs-only AIOS updates can be committed directly when low risk and requested.
- Production-affecting changes require explicit scope and verification.
- If a repo has existing unpushed commits, preserve them and push together only if fast-forward safe.
- If multiple remotes diverge, push topic branch rather than forcing defaults.

### Telegram Update Rules

For AIOS routines, messages should be concise and action-first:

```text
1️⃣ AIOS weekly audit complete
- Score: 76/100 (+4)
- Top gap: connection registry freshness
- Action: approve docs/ecosystem/aios/CONNECTIONS_REGISTRY.md update
- Evidence: commit <sha>, report path <path>
```

### Kill Switch Rules

Every routine must document:

- how to pause it
- how to remove it
- where logs/output live
- who receives failures
- what conditions require disabling it

---

## Risk Register

| Risk                    | Impact                                           | Mitigation                                                                   |
| ----------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| Agent over-autonomy     | Production breakage or unwanted external actions | L0-L4 policy, approval gates, read-only first, Telegram review               |
| Context leakage         | Secrets or private data in docs/memory           | No raw secrets, env var names only, repo review before commit                |
| Automation sprawl       | Too many routines nobody trusts                  | Capability catalog, routine registry, kill switches, weekly audit            |
| Stale documentation     | Wrong actions based on old assumptions           | Freshness checks, source-of-truth hierarchy, recurring audit                 |
| Model/tool churn        | Claude/Hermes/provider behavior changes          | Keep workflows tool-agnostic; deterministic scripts before AI calls          |
| Hidden maintenance cost | Automations cost more than manual work           | Tie every capability to KPI and kill low-value routines                      |
| Single-VM blast radius  | Agent changes can affect many services           | Production-safe gate, backups, rollback commands, no public Hermes dashboard |

---

## KPIs To Track

### Leverage KPIs

- Hours/week saved from repeated operations.
- Number of recurring tasks handled by AIOS at L2+.
- Number of manual status checks replaced by briefs.
- Time from user request to committed plan/doc/patch.

### Quality KPIs

- Percentage of AIOS outputs requiring correction.
- Failed cron/routine count per week.
- Number of stale connection entries.
- Number of docs with broken source-of-truth assumptions.

### Safety KPIs

- Production-affecting actions without approval: target 0.
- Secrets committed: target 0.
- Unreviewed public exposure changes: target 0.
- Routines without kill switch: target 0.

---

## Recommended Immediate Decision

Approve **Phase 0** as the next implementation slice:

1. Create `docs/ecosystem/aios/`.
2. Add AIOS README, autonomy policy, connection registry, capability catalog, and audit template.
3. Link it from ecosystem docs.
4. Keep all automation at L1/L2 until the first audit and registry are reviewed.

This gives ByteLyst the benefits of the AIOS pattern quickly without granting risky autonomy.

---

## Appendix A: External Concepts Worth Reusing With Attribution

The AIS-OS public repository includes MIT-licensed starter-kit concepts and explicitly attributes several frameworks to Nate Herk. If ByteLyst references these externally, preserve attribution.

Concepts worth reusing internally:

- Four C's architecture: Context, Connections, Capabilities, Cadence.
- Three M's operating lens: Mindset, Method, Machine.
- Bike Method rollout: Training Wheels → Guided → Watched → Hands-off.
- Intern Rule: own identity, scoped permissions, read-only first, audit trail.
- Kill Switch: remove automations that do not earn their keep.
- “Boring is beautiful”: deterministic workflows before agentic complexity.

ByteLyst-specific framing should be original:

- Hermes-native operating layer.
- Telegram-first approval and reporting.
- Common-platform-backed agent contracts.
- Gitea/GitHub dual-remote execution model.
- Single-VM production safety gates.

---

## Appendix B: Candidate ByteLyst AIOS Files To Create Next

```text
docs/ecosystem/aios/README.md
docs/ecosystem/aios/CONTEXT_PACK.md
docs/ecosystem/aios/CONNECTIONS_REGISTRY.md
docs/ecosystem/aios/CAPABILITY_CATALOG.md
docs/ecosystem/aios/CADENCE_REGISTRY.md
docs/ecosystem/aios/AUTONOMY_POLICY.md
docs/ecosystem/aios/AUDIT_SCORECARD.md
docs/ecosystem/aios/ROADMAP.md
```

---

## Appendix C: First Candidate Cadences

| Routine                    | Schedule                 | Output                              | Autonomy             | Risk   |
| -------------------------- | ------------------------ | ----------------------------------- | -------------------- | ------ |
| Daily operator brief       | Weekdays 08:00 Pacific   | Telegram summary                    | L2                   | Low    |
| Weekly AIOS audit          | Friday afternoon Pacific | Markdown report + Telegram          | L2/L3                | Low    |
| Connection freshness check | Weekly                   | Registry drift report               | L3 read-only         | Low    |
| Capability catalog drift   | Weekly                   | Stale/missing skills/scripts report | L3 read-only         | Low    |
| Backup verification        | Daily                    | Silent unless failure               | L4 if already proven | Medium |
| Gitea runner health        | Daily                    | Telegram on failure                 | L3                   | Medium |
| Docs broken-link scan      | Weekly                   | Issue/patch draft                   | L2/L3                | Low    |
| Production exposure audit  | Weekly                   | Report only                         | L2                   | Medium |

---

## Appendix D: First Candidate Connections

- Telegram home channel.
- Hermes memory/profile/session search.
- Hermes skills directory.
- Hermes cron scheduler.
- `learning_ai_common_plat` GitHub remote.
- `learning_ai_common_plat` local Gitea remote.
- ByteLyst devops tools repo.
- Docker engine on Hostinger VM.
- systemd services.
- Caddy config.
- Gitea Actions runner.
- Google Drive `hemes_files` folder.
- FreeLLMAPI local service.
- MarkItDown local utility.
- Platform service health endpoints.
- MCP server tools.
- Extraction service.

---

## Appendix E: Recommended Prompt For Future AIOS Audit Runs

```text
Run a ByteLyst AIOS audit. Use docs/ecosystem/AIOS_ADOPTION_ROADMAP_2026-05-29.md as the roadmap, inspect docs/ecosystem/aios if it exists, check Hermes skills/cron, check active repo git state, and produce a Four C's score with top 3 gaps. Do not mutate production systems. If you write files, use docs/ecosystem/aios/audits/YYYY-MM-DD.md and commit only docs changes.
```
