Cloud X Berry — Engineering Playbook for the SolOS v2 Rebuild

Source: 8 full transcripts from the "Cloud X Berry" YouTube channel, pulled with youtube-transcript-api (Tam profile venv, ~/.hermes/profiles/tam/venv) into /tmp/yt_.txt. Transcript sizes: 3.6–8.9 KB each — all verified non-empty and plausible. Distilled by Tam for Sol (engineering lead) + Ace (developer), SolOS v2 rebuild.

Per-Video Core Teachings

1. qvjRcZcW8CY — Linux File Directories (7.1 KB)

• Single rooted tree, not drive letters; everything hangs off /.
• Group directories by purpose: user data /home, programs /bin+/sbin+/usr, config /etc, shared libs /lib.
• /root ≠ /: one is the FS root, the other the admin's home — naming matters, don't confuse.
• /etc is the OS-wide settings folder; config lives outside the application binary.
• /usr = Unix System Resources (not "user"), the main software library.
• Shared libraries: common code stored once and borrowed — don't duplicate.
• /tmp is disposable (wiped on boot) — never store anything important there.
• /var = variable/changing data; /var/log is the first stop for troubleshooting.
• Removable storage mounts INTO the tree (/media, /mnt), not as separate drives.
• /dev: "everything is a file" — hardware exposed through a uniform file interface.
• /proc is a virtual kernel FS — live system dashboard, not on disk.
• Remember by job, not by name: files / programs / config / libs / logs / tmp / devices / proc / boot / mounts.

2. JcYMtYbNUhU — 7 Coding Laws of Senior Developers (6.5 KB)

• Underlying principle of all seven: make the next change easier.
• Keep the main path easy to follow — early returns over 3-level nesting; bury the happy-path logic nowhere.
• Name by meaning: pendingOrder, not data/result/item; good names kill detective work.
• Keep external systems behind a boundary — convert external API field names to your own vocabulary in ONE place so external changes don't ripple.
• Make invalid states harder to represent: types that carry guarantees (PaidOrder has paymentId guaranteed) instead of everything-optional.
• Separate decisions from actions: eligibility logic testable WITHOUT invoking DB/email side effects.
• Make errors useful: text is for humans, codes are for systems; log context but never secrets/passwords/tokens.
• Keep changes focused: one PR = one purpose; small changes are easier to review, test, debug, roll back.

3. Y01eR7tUgnc — 5 DSA Patterns Solve 90% of Problems (5.8 KB)

• Most problems are old patterns in new clothes — recognize before coding.
• Sliding window: moving continuous stretch (fixed or grow/shrink by condition); reuse work by subtracting the expiring element.
• Two pointers: sorted input, two positions moving under a rule; each move eliminates impossible options.
• Prefix sum: precompute running totals once, answer repeated range-sum queries with one subtraction.
• Binary search: sorted / half-decidable space → check middle, eliminate half.
• Kadane's algorithm: best continuous subarray sum in one pass — "extend or restart?" at each step.
• Rule: don't memorize algorithms; read the problem for the CLUE (moving range? sorted pair? range totals? halve-able? continuous best).

4. -40xErgJIBg — 8 API Laws of Senior Backend Engineers (8.9 KB)

• Design around RESOURCES not actions: URL identifies the thing, HTTP method describes the operation.
• Predictable URLs: consistent collection naming + one casing convention + IDs for single resources; a predictable API needs fewer instructions.
• Use HTTP methods for their actual semantics (GET/POST/PUT/PATCH/DELETE) and respect idempotency — networks retry.
• Status codes must mean something: 200/201/202/204, 400/401/403/404/409/422/429; never 200 OK with failure in the body.
• Structured errors: error code + message + status (+ per-field validation details) — never "something went wrong".
• Paths identify, query params refine; never invent actions via ?action=delete on GET.
• Versioning: ask first whether a change is breaking; non-required adds usually aren't; when breaking, use ONE obvious strategy and give consumers a migration path.
• Consistency of formats beats a rulebook: one date format, one pagination style, one error shape — "make the next endpoint look familiar".
• A good API is judged by whether clients can use it without constantly checking docs — define the patterns BEFORE building endpoint by endpoint.

5. 7yNvsFrwpp0 — MCP vs API (6.1 KB)

• MCP does NOT replace APIs — it sits ON TOP of them as an adapter to AI applications.
• API world: the developer hardcodes the workflow (which calls, which order). MCP world: the developer exposes capabilities; the model chooses.
• Tool = an action the AI can perform; Resource = information (files, docs, records) the AI can read.
• MCP server exposes tools with standardized descriptions + input schemas — discovery replaces documentation-reading.
• Existing APIs stay untouched behind the MCP server: get_customer / get_latest_order / send_email tools call the same customer/orders/email APIs.
• Gate: MCP is for AI-initiated flows where intent is natural language; predefined deterministic workflows remain plain API code.
• Adding a capability = adding a tool; the AI app discovers it on next connect — no client rewrite.
• Bridge model: user intent → model picks tools → MCP server invokes existing APIs → results back. Business logic lives in existing systems.

6. XvziDv-rFxU — Vibe Coders vs Real Coders: Big O derived, not memorized (7.2 KB)

• Timing an algorithm measures algorithm + machine together; count STEPS instead, with an agreed counting model.
• The constant depends on your counting model AND your hardware — it can't be trusted, so discard it.
• Hardware moves the constant; the algorithm moves the SHAPE. Keep the shape (biggest-growing term), throw the rest away.
• Derivation procedure: count → drop constants and lower-order terms → dominant term = Big O.
• Big O is a TIGHT simple bound on growth, not seconds, not exact steps.
• Big O won't tell you which is faster for small n — below some size, the "worse" algorithm always wins.
• Big O conventionally bounds the WORST case — always ask which case a quoted bound refers to.
• It hides constants; two O(n) algorithms can differ 50× in reality — pick inputs sized like production.
• Big O answers exactly one question well: when input grows big, how does work grow?
• Vibe-coder tell: judging code by "it works on my laptop" instead of reasoning about growth and shape.

7. Q6ZDabgXeLk — Coding Fundamentals: what actually happens when code runs (5.3 KB)

• Computers understand only machine code; your code must be translated (compiler/interpreter).
• Full chain: your code → app → OS → hardware → result flows back up. The OS is the manager; apps don't touch hardware directly.
• Hardware model: CPU executes, RAM holds active data, storage persists.
• All software is input → process → output. Recognize the pattern in every feature you build.
• Languages differ by purpose (web, backend, automation, games) but all bottom out in machine instructions.
• The computer is fast but literal: wrong output means wrong instructions — it followed them perfectly.
• Engineering mindset: stop memorizing syntax; understand the system you're instructing.

8. rf5zi3Y4ziQ — Why Learn Data Structures in 2026 (3.6 KB)

• Data must be ORGANIZED for access, search, and operation — random storage fails real products.
• Netflix example: search (titles/genres), browse (many small trailers), watch (one huge file) — three different use patterns demand three different storage strategies.
• Match the structure to the ACCESS pattern, not to fashion: how is this data used?
• Array: fixed size, uniform type, O(1) index access — "carton of eggs".
• List: dynamic size, flexible growth/shrink — "line of people".
• Arrays when size/shape is fixed; lists when size changes frequently.
• Programming is choosing the right structure for the data, not just writing code.

Synthesis

A) DSA + API Design Rules (videos 3, 4, 8, 6)

1. Pattern-recognition before coding: classify the problem (moving stretch → sliding window; sorted pair → two pointers; repeated range sums → prefix sum; halve-able space → binary search; best continuous subarray → Kadane's).
2. Reuse computed work — never re-add a window from scratch; precompute (prefix sums) where queries repeat.
3. Choose data structures by access pattern: arrays for fixed/indexed, lists for dynamic; different access = different storage (Netflix rule).
4. Resource-first APIs: URL = noun, method = verb; no getUser/createOrder style endpoint naming.
5. Method semantics + idempotency are load-bearing: ret/stale networks will repeat requests; design for it.
6. Truthful status codes — a 200 must never carry a failure; map 400/401/403/404/409/422/429 deliberately.
7. Structured, consistent error envelope everywhere (code + message + field details).
8. Path vs query parameter responsibility split; no actions smuggled into GET.
9. Version for breakage, not convenience; one strategy, migration path always.
10. Define API-wide conventions (naming, dates, pagination, errors) BEFORE writing endpoints; "make the next endpoint look familiar".
11. Reason about growth, not wall-clock: count steps, drop constants and lower terms, keep the shape; know Big O's limits (small-n constants, hidden constant factors, worst-case convention).

B) Senior Developer Craft (videos 2, 7 + 8)

1. Every change should make the NEXT change easier — the master rule.
2. Guard-clause main paths: early returns, no buried happy logic.
3. Meaningful names communicate intent and eliminate detective work; ban data/result/item in business code.
4. External systems behind anti-corruption boundaries; external field names never leak inward.
5. Encode invariants in types so invalid states are unrepresentable (PaidOrder owns its paymentId).
6. Pure decision logic separated from side effects → testability without DB/email.
7. Error handling discipline: codes for systems, text for humans, context in logs, secrets never logged.
8. Focused changes only: one purpose per commit/PR; direct consequence is easy review, test, rollback.
9. Understand the execution chain (code → app → OS → hardware) and the input→process→output model before optimizing anything.
10. Config lives outside the binary (/etc principle); shared code lives as libraries, never copy-pasted.

C) MCP / API for Agent-Tool Architectures (video 5, informed by 4 and 2)

1. MCP is an adapter, not a replacement — SolOS keeps its internal APIs as the foundation; the MCP/plugin layer exposes them to OpenCode agents.
2. Design tools as MODEL-FACING capabilities, not verbatim API mirrors: coarse, intent-shaped tools (get_latest_order) over raw CRUD endpoints.
3. Tool descriptions + input schemas ARE the interface — write them like API docs, because the model does discovery via them.
4. Expose verbs the user's intent implies; the model composes the workflow, so tools must be independently meaningful and idempotent-safe (video 4's idempotency now protects retries initiated by an agent).
5. Keep business logic in existing services; MCP server is a thin, stateless translation layer.
6. Error payloads must be tool-friendly: structured codes + safe messages — for humans, codes for (agent) systems; an agent's recovery logic keys off codes, not prose.
7. New capability = new tool, discovered next connection — SolOS plugin additions shouldn't require client rewrites; version the MCP surface the way video 4 versions APIs.
8. Boundaries apply doubly: external-API field names must be normalized at the MCP server edge before reaching the model context.

D) 'Vibe Coding' Warnings — flags for the 27 bare-except + hand-patch issues (videos 2, 6, 7, 4, 8)

Vibe-coding tells and their systemic causes:

1. Bare except: / "something went wrong" — violates the errors law (untextable/unsystematic failure). Flag: no error codes, no context, secrets possibly logged. Fix: typed exceptions with codes; catch what you can handle specifically.
2. Hand-patched fixes — fixing symptoms at the call site instead of the invariant. Flag: same bug patched 3 ways in 3 places = the invariant lives nowhere. Fix: encode the invariant in a type or single function.
3. data/result/tmp naming everywhere — meaning deferred to the reader; the detective-work smell.
4. 200-OK-wrapping errors — "it technically works" without protocol semantics; the vibe coder ships whatever makes the E2E test pass.
5. Unbounded/nested try-everything paths — opposite of the main-path law; buried logic hides what the function actually does.
6. Timing-based or acceptance-test-based quality judgment ("it ran fine") — video 6's core error: measuring the machine/context, not the algorithm's growth shape.
7. Everything optional / defensive if x: checks scattered everywhere — a symptom of types that permit invalid states.
8. Decisions welded to side effects — business rules untestable without live DBs/emails; leads to skippable tests, which is where vibe code survives longest.
9. Copy-pasted "shared" code — the anti-library; video 1's /lib principle and the array-vs-list discipline both punish duplication.
10. God-PRs / sweeping hand-edits — mixing feature+refactor+data changes makes review meaningless; vibe fixes get merged because nobody can review them.

TOP-10 Action Items for the SolOS v2 Rebuild

1. Exterminate all 27 bare excepts: conditional, typed exceptions carrying structured {code, message, status} — adopt one error envelope repo-wide (videos 2, 4, D-section).
2. Define the v2 API convention doc BEFORE any endpoint code: resource naming, casing, dates, pagination, filtering, error shape, versioning strategy (video 4's closing rule).
3. Fix the hand-patch root causes: for each, identify the underlying invariant and encode it in a type/domain model so the invalid state is unrepresentable (video 2).
4. Guard-clause refactor hot paths: early returns, no business logic buried ≥3 levels deep (v2 rules module) (video 2).
5. Split decision from side effects in eligibility/permission/pricing logic → unit-testable pure functions, no live service calls (video 2).
6. Architect the MCP/plugin layer as a thin adapter over existing SolOS services: intent-shaped tools with rich descriptions/schemas, stateless translation, business logic stays put (video 5).
7. Set per-tool idempotency labels so agent retries are safe (GET/PUT/DELETE idempotent; POST create has explicit dedupe/event-ID strategy) (videos 4+5).
8. Add Big-O reasoning to review checklist: any O(n²) scan over user-scale data needs a pattern upgrade (sliding window / two pointers / prefix sum / hash index) (videos 3, 6).
9. Repo & config hygiene: single-source config (no config in code), no important data in temp, shared utilities as one library not copies — the FHS /etc+/lib principles applied to the repo (videos 1, 8).
10. Adopt "make the next change easier" as the review question: every PR states which invariant/name/boundary it improves; reject multi-purpose edits (video 2).

Per-video source files

1. /tmp/yt_qvjRcZcW8CY.txt (7.1 KB) — Linux FS
2. /tmp/yt_JcYMtYbNUhU.txt (6.5 KB) — 7 coding laws
3. /tmp/yt_Y01eR7tUgnc.txt (5.8 KB) — 5 DSA patterns
4. /tmp/yt_-40xErgJIBg.txt (8.9 KB) — 8 API laws
5. /tmp/yt_7yNvsFrwpp0.txt (6.1 KB) — MCP vs API
6. /tmp/yt_XvziDv-rFxU.txt (7.2 KB) — Big O / vibe coders
7. /tmp/yt_Q6ZDabgXeLk.txt (5.3 KB) — coding fundamentals
8. /tmp/yt_rf5zi3Y4ziQ.txt (3.6 KB) — why data structures