Inside ichi — WkndPrjcthttps://wkndprjct.id/handbook/The ichi engineering handbook — how a personal AI operating system is designed, why each decision was made, and how the ecosystem fits together. Reasoning over implementation.en-usThu, 09 Jul 2026 07:15:04 +0000What is ichi?https://wkndprjct.id/handbook/what-is-ichi/https://wkndprjct.id/handbook/what-is-ichi/Mon, 01 Jan 0001 00:00:00 +0000ichi is a personal AI operating system: one person, a body of knowledge, and a small organisation of AI agents that help operate work, sharpen thinking, and publish what is worth sharing. It is not an app. It is an ecosystem with three products (Chapter 05) and one operating principle: the machine proposes; the human disposes.ichi is a personal AI operating system: one person, a body of knowledge, and a small organisation of AI agents that help operate work, sharpen thinking, and publish what is worth sharing.

It is not an app. It is an ecosystem with three products (Chapter 05) and one operating principle: the machine proposes; the human disposes.

Mission

Turn one person’s knowledge and judgment into leverage — without handing judgment to the machine.

Vision

A system where AI does the gathering, connecting, drafting, and monitoring, and a human does the deciding. Speed from automation; direction from a person.

Core philosophy

  • Everything is connected. Ideas, systems, and decisions share structure across domains. The same shape appears in a market, a codebase, and a body.
  • Less, but better. Fewer moving parts, higher quality. Boring technology that fails predictably.
  • Human judgment is the final authority. Every gate has a person at it. Nothing ships automatically.
  • Documentation compounds. What is written down keeps paying returns long after it is written.

The implementation will change. These principles are meant to last. This handbook documents the reasoning — so that even when the tools are replaced, the why survives.

]]>High-Level Architecturehttps://wkndprjct.id/handbook/architecture/https://wkndprjct.id/handbook/architecture/Mon, 01 Jan 0001 00:00:00 +0000ichi is a pipeline of trust. Signal and work flow down; only proposals flow back up. Nothing crosses the human gate without approval. Expand diagram flowchart TD H["Human — intent + final approval"] --> K["Knowledge — the vault / memory"] K --> OS["AI Operating System — agents that gather, connect, monitor, draft"] OS --> EO["Executive Office — a virtual C-suite that reviews"] EO --> P["Products — what the system ships"] P --> R["Readers — receive only finished, approved work"] The layers Layer Role Human The origin and the final gate. Sets intent; approves or rejects output. Knowledge A single vault of notes, logs, and drafts. The system’s memory (Chapter 04). AI Operating System Agents that gather signals, connect ideas, monitor health, and draft. Executive Office A virtual C-suite that reviews the same work from many angles (Chapter 03). Products ichiOS, Brain, WkndPrjct (Chapter 05). Readers The public. They see only the finished, human-approved result. Why one direction The arrows are one-way for action. An agent can draft an essay, flag an anomaly, or propose a decision — but it cannot publish, spend, or ship. Those actions return to the human gate first.ichi is a pipeline of trust. Signal and work flow down; only proposals flow back up. Nothing crosses the human gate without approval.

flowchart TD H["Human — intent + final approval"] --> K["Knowledge — the vault / memory"] K --> OS["AI Operating System — agents that gather, connect, monitor, draft"] OS --> EO["Executive Office — a virtual C-suite that reviews"] EO --> P["Products — what the system ships"] P --> R["Readers — receive only finished, approved work"]

The layers

Layer Role
Human The origin and the final gate. Sets intent; approves or rejects output.
Knowledge A single vault of notes, logs, and drafts. The system’s memory (Chapter 04).
AI Operating System Agents that gather signals, connect ideas, monitor health, and draft.
Executive Office A virtual C-suite that reviews the same work from many angles (Chapter 03).
Products ichiOS, Brain, WkndPrjct (Chapter 05).
Readers The public. They see only the finished, human-approved result.

Why one direction

The arrows are one-way for action. An agent can draft an essay, flag an anomaly, or propose a decision — but it cannot publish, spend, or ship. Those actions return to the human gate first.

This is the single most important design choice in ichi, and it is not a technical one. It is a governance one: automation earns trust by being reversible and gated, not by being autonomous.

]]>Productshttps://wkndprjct.id/handbook/products/https://wkndprjct.id/handbook/products/Mon, 01 Jan 0001 00:00:00 +0000ichi ships three products. Each stands alone, but they are designed to feed one another. Expand diagram flowchart LR OS["ichiOS<br/>operate work"] --> B["Brain<br/>improve thinking"] B --> W["WkndPrjct<br/>share knowledge"] W -.insight.-> B B -.memory.-> OS ichiOS — operate work The operating layer: a hub of small personal apps (tasks, calendar, finance, notes) and the AI agents that keep them running. Its job is to remove operational drag so attention can go to thinking.ichi ships three products. Each stands alone, but they are designed to feed one another.

flowchart LR OS["ichiOS<br/>operate work"] --> B["Brain<br/>improve thinking"] B --> W["WkndPrjct<br/>share knowledge"] W -.insight.-> B B -.memory.-> OS

ichiOS — operate work

The operating layer: a hub of small personal apps (tasks, calendar, finance, notes) and the AI agents that keep them running. Its job is to remove operational drag so attention can go to thinking.

Brain — improve thinking

The knowledge layer: a single vault plus an intelligence layer that can answer questions across everything written, surface connections, and flag stale knowledge. It turns a pile of notes into something you can ask.

WkndPrjct — share knowledge

The public layer: a publication of essays on the patterns that recur across technology, history, systems, and human behaviour. It is where private thinking becomes public writing.

Why they exist together

Operating work generates knowledge. Knowledge, connected, produces insight. Insight, refined, becomes something worth publishing. And publishing forces the thinking to be clear enough to survive a reader.

The loop is the point: operate → learn → share → operate better. No single product is the goal; the compounding between them is.

]]>Technology Stackhttps://wkndprjct.id/handbook/technology/https://wkndprjct.id/handbook/technology/Mon, 01 Jan 0001 00:00:00 +0000The through-line of every choice below is the same: local-first, plain-text, scriptable, and boring. Boring technology fails in predictable ways, and predictable failure is cheap to fix. Infrastructure Tool Why Alternative Trade-off Cloud VPS Full control, flat cost, no lock-in Managed PaaS We own the operations Nginx Simple, fast static serving Caddy, Apache Manual configuration Cloudflare Free CDN, TLS, and edge protection Bare origin A dependency at the edge Git hosting Versioned single source of truth Cloud file sync Requires discipline Knowledge Tool Why Alternative Trade-off Obsidian Local-first Markdown, zero lock-in Notion No real-time collaboration Markdown Portable, diffable, durable Rich database Less enforced structure AI Tool Why Alternative Trade-off Claude CLI A scriptable reasoning engine that runs on our terms Hosted bot APIs We wire the orchestration AI Executive Office Many expert viewpoints from one model A single generalist prompt Coordination overhead Development &amp;amp; Publishing Tool Why Alternative Trade-off Hugo Fast static generation WordPress, Next.js A build step Python Glue for every automation Shell everywhere Another runtime Mermaid Diagrams as versioned text Image files Renders client-side Open Graph / SEO Discoverable and shareable by default Nothing Metadata upkeep Automation &amp;amp; Communication Tool Why Alternative Trade-off Cron + Git + SSH Boring, reliable plumbing Heavy orchestrators Manual wiring Telegram Instant human-in-the-loop channel Email, chat apps One more surface Every row is a small bet that a simpler tool, well understood, beats a powerful tool, poorly understood. The detailed reasoning behind the biggest bets lives in Chapter 07.The through-line of every choice below is the same: local-first, plain-text, scriptable, and boring. Boring technology fails in predictable ways, and predictable failure is cheap to fix.

Infrastructure

Tool Why Alternative Trade-off
Cloud VPS Full control, flat cost, no lock-in Managed PaaS We own the operations
Nginx Simple, fast static serving Caddy, Apache Manual configuration
Cloudflare Free CDN, TLS, and edge protection Bare origin A dependency at the edge
Git hosting Versioned single source of truth Cloud file sync Requires discipline

Knowledge

Tool Why Alternative Trade-off
Obsidian Local-first Markdown, zero lock-in Notion No real-time collaboration
Markdown Portable, diffable, durable Rich database Less enforced structure

AI

Tool Why Alternative Trade-off
Claude CLI A scriptable reasoning engine that runs on our terms Hosted bot APIs We wire the orchestration
AI Executive Office Many expert viewpoints from one model A single generalist prompt Coordination overhead

Development & Publishing

Tool Why Alternative Trade-off
Hugo Fast static generation WordPress, Next.js A build step
Python Glue for every automation Shell everywhere Another runtime
Mermaid Diagrams as versioned text Image files Renders client-side
Open Graph / SEO Discoverable and shareable by default Nothing Metadata upkeep

Automation & Communication

Tool Why Alternative Trade-off
Cron + Git + SSH Boring, reliable plumbing Heavy orchestrators Manual wiring
Telegram Instant human-in-the-loop channel Email, chat apps One more surface

Every row is a small bet that a simpler tool, well understood, beats a powerful tool, poorly understood. The detailed reasoning behind the biggest bets lives in Chapter 07.

]]>Architecture Decisionshttps://wkndprjct.id/handbook/decisions/https://wkndprjct.id/handbook/decisions/Mon, 01 Jan 0001 00:00:00 +0000Architecture Decision Records (ADRs) capture why, not just what. Implementations change; a good ADR explains the thinking so the next decision has context. ADR-001 · A static site Problem: Publish essays reliably, at near-zero cost, with the smallest possible attack surface. Options: A CMS (WordPress); an app framework (Next.js); a static generator. Decision: Static generation with Hugo. Trade-off: No server-side features without extra work; every change needs a build. Outcome: Sub-500ms loads, no database to breach, no runtime to patch, negligible hosting cost. ADR-002 · Markdown in a local vault Problem: Where should knowledge live so it survives tool changes and stays fully owned? Options: A hosted knowledge app; a database; local Markdown files. Decision: Local-first Markdown (Obsidian over plain files). Trade-off: Less enforced structure; no real-time collaboration. Outcome: Knowledge is diffable, portable, and outlives any single app. Nothing is trapped behind an API. ADR-003 · Claude CLI as the reasoning engine Problem: Automation needs judgment — drafting, reviewing, answering — not just scripts. Options: Hosted bot APIs with a fixed budget; a self-hosted model; a scriptable CLI. Decision: Claude CLI, invoked from ordinary automation. Trade-off: We build the orchestration ourselves. Outcome: Reasoning becomes a Unix-style tool — pipe text in, get judgment out — usable by any cron job or script, on our terms. ADR-004 · Human approval at every gate Problem: How much autonomy should the agents have? Options: Full autonomy (agents act); no autonomy (agents only advise); gated autonomy (agents act, humans approve). Decision: Gated. Agents draft, monitor, and propose; a person approves anything that ships, spends, or publishes. Trade-off: The human is a bottleneck by design. Outcome: Automation earns trust by being reversible and gated — not by being unsupervised. The bottleneck is the safety mechanism. More ADRs — why Telegram, why not a database, why an AI Executive Office — are answered in short form in Chapter 12.Architecture Decision Records (ADRs) capture why, not just what. Implementations change; a good ADR explains the thinking so the next decision has context.

ADR-001 · A static site

  • Problem: Publish essays reliably, at near-zero cost, with the smallest possible attack surface.
  • Options: A CMS (WordPress); an app framework (Next.js); a static generator.
  • Decision: Static generation with Hugo.
  • Trade-off: No server-side features without extra work; every change needs a build.
  • Outcome: Sub-500ms loads, no database to breach, no runtime to patch, negligible hosting cost.

ADR-002 · Markdown in a local vault

  • Problem: Where should knowledge live so it survives tool changes and stays fully owned?
  • Options: A hosted knowledge app; a database; local Markdown files.
  • Decision: Local-first Markdown (Obsidian over plain files).
  • Trade-off: Less enforced structure; no real-time collaboration.
  • Outcome: Knowledge is diffable, portable, and outlives any single app. Nothing is trapped behind an API.

ADR-003 · Claude CLI as the reasoning engine

  • Problem: Automation needs judgment — drafting, reviewing, answering — not just scripts.
  • Options: Hosted bot APIs with a fixed budget; a self-hosted model; a scriptable CLI.
  • Decision: Claude CLI, invoked from ordinary automation.
  • Trade-off: We build the orchestration ourselves.
  • Outcome: Reasoning becomes a Unix-style tool — pipe text in, get judgment out — usable by any cron job or script, on our terms.

ADR-004 · Human approval at every gate

  • Problem: How much autonomy should the agents have?
  • Options: Full autonomy (agents act); no autonomy (agents only advise); gated autonomy (agents act, humans approve).
  • Decision: Gated. Agents draft, monitor, and propose; a person approves anything that ships, spends, or publishes.
  • Trade-off: The human is a bottleneck by design.
  • Outcome: Automation earns trust by being reversible and gated — not by being unsupervised. The bottleneck is the safety mechanism.

More ADRs — why Telegram, why not a database, why an AI Executive Office — are answered in short form in Chapter 12.

]]>Engineering Principleshttps://wkndprjct.id/handbook/principles/https://wkndprjct.id/handbook/principles/Mon, 01 Jan 0001 00:00:00 +0000Tools change. Principles are how ichi stays coherent across those changes. Each one is a tiebreaker for real decisions. Everything is connected The same structure recurs across domains. Solve a problem well in one place and you have likely solved it in three. Design for the connection, not the instance.Tools change. Principles are how ichi stays coherent across those changes. Each one is a tiebreaker for real decisions.

Everything is connected

The same structure recurs across domains. Solve a problem well in one place and you have likely solved it in three. Design for the connection, not the instance.

Less, but better

Fewer parts, higher quality. Every added tool, feature, or service is a standing liability. The default answer to “should we add this?” is no.

Documentation compounds

Writing down the reasoning pays returns long after the code is gone. A decision explained once saves the same argument ten times. This handbook exists because of this principle.

Human judgment is the final authority

Automation proposes; a person disposes. Nothing ships, spends, or publishes without a human gate. Speed is delegated; direction is not.

Engineering economics

Every choice has a carrying cost — attention, maintenance, failure modes. Optimise for total cost of ownership over time, not the cleverness of the moment. Boring is cheaper.

Platform first

Build capabilities that many things can use, not features that serve one case. A reasoning engine, a knowledge layer, a publishing pipeline — each is a platform other work stands on.

Single source of truth

One canonical place for each kind of knowledge. Duplication is where drift begins, and drift is where trust dies. When two records disagree, the system has already failed.

]]>Frequently Asked Questionshttps://wkndprjct.id/handbook/faq/https://wkndprjct.id/handbook/faq/Mon, 01 Jan 0001 00:00:00 +0000Why Hugo? Because a publication should be stone, not software. Static generation gives sub-500ms pages, nothing to breach, and near-zero cost. The price is a build step — a fair trade. Why Markdown? Because knowledge should outlive its tools. Markdown is portable, diffable, and readable in any text editor thirty years from now. A proprietary format is a slow-motion hostage situation.Why Hugo?

Because a publication should be stone, not software. Static generation gives sub-500ms pages, nothing to breach, and near-zero cost. The price is a build step — a fair trade.

Why Markdown?

Because knowledge should outlive its tools. Markdown is portable, diffable, and readable in any text editor thirty years from now. A proprietary format is a slow-motion hostage situation.

Why Obsidian?

Because it is Markdown, local-first, with no lock-in. The files are yours whether Obsidian exists tomorrow or not. It adds linking and graphing without taking ownership of the data.

Why an AI Executive Office?

Because one generalist prompt gives one perspective. Framing the same work through many roles — security, product, operations, knowledge — surfaces problems a single viewpoint misses. It is diversity of attention, from one model.

Why Telegram?

Because the human gate needs a channel that is instant and always in the pocket. A proposal that waits in an inbox is a proposal that stalls. Telegram is the fastest path to a yes or a no.

Why not a database?

Because a database is a running service to secure, back up, and patch — and the content is small and mostly text. Plain files in version control give durability and history for none of the operational cost.

Why static?

Because the safest server is the one that does nothing. No runtime means no runtime vulnerabilities. Every dynamic feature must justify the attack surface it adds; most cannot.

]]>