docs: add ByteLyst AIOS adoption roadmap

2026-05-29 21:26:23 +00:00 · 2026-05-29 21:26:23 +00:00 · fff5d993ba
commit fff5d993ba
parent fe8338c2c5
2 changed files with 882 additions and 0 deletions
--- a/docs/ecosystem/AIOS_ADOPTION_ROADMAP_2026-05-29.md
+++ b/docs/ecosystem/AIOS_ADOPTION_ROADMAP_2026-05-29.md
@ -0,0 +1,881 @@
 # 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.
 ```
--- a/docs/ecosystem/README.md
+++ b/docs/ecosystem/README.md
@ -16,6 +16,7 @@ Recommended structure:
 - [`ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md) — strategy, opportunities, gaps, priorities
 - [`ECOSYSTEM_IMPLEMENTATION_TRACKER.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md) — canonical execution tracker with checkboxes and commit references
 - [`ECOSYSTEM_AGENT_OPERATING_MODEL.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md) — delegation, review, merge, and tracker-update process for Saravana, Codex, Windsurf, and Cursor
 - [`AIOS_ADOPTION_ROADMAP_2026-05-29.md`](./AIOS_ADOPTION_ROADMAP_2026-05-29.md) — roadmap for adopting an AI Operating System layer across Hermes, ByteLyst platform services, repo docs, skills, connections, and cadence routines
 - [`ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md) — canonical artifact model
 - [`ECOSYSTEM_EVENT_TAXONOMY.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md) — shared events and action-log contract
 - [`ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md) — shared session, todo, resume, dispatch semantics