Shiguchi

A model. A route. A working API.

Describe a Todo and how the world reaches it. With Koan’s web foundation and SQLite connector, these declarations give it a persisted, queryable HTTP API.

Model declaration

public sealed class Todo : Entity<Todo>
{
    public string Title { get; set; } = "";

    public bool Done { get; set; }
}

View this source excerpt →

Route declaration

[Route("api/todos")]
public sealed class TodosController : EntityController<Todo>;

View this source excerpt →

See all four application files

Program.cs

using Koan.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddKoan();
var app = builder.Build();
await app.RunAsync();

View this source excerpt →

Todo.cs

using Koan.Data.Abstractions;
using Koan.Data.Core.Model;

namespace KoanWebApp;

public sealed class Todo : Entity<Todo>
{
    public string Title { get; set; } = "";

    public bool Done { get; set; }
}

View this source excerpt →

TodosController.cs

using Koan.Web.Controllers;
using Microsoft.AspNetCore.Mvc;

namespace KoanWebApp;

[Route("api/todos")]
public sealed class TodosController : EntityController<Todo>;

View this source excerpt →

KoanWebApp.csproj

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Sylin.Koan.App" Version="1.*" />
    <PackageReference Include="Sylin.Koan.Data.Connector.Sqlite" Version="1.*" />
  </ItemGroup>

</Project>

View this source excerpt →

One AddKoan() composes the referenced capabilities. Application code owns the business; Koan owns composition, provider selection, and infrastructure lifecycle.

Make something you can keep.

Start with the .NET 10 SDK. These PowerShell commands create the application shown above, using published NuGet packages and local SQLite storage.

Create and run

$ dotnet new install Sylin.Koan.Templates dotnet new koan-web -o TodoApi cd TodoApi dotnet run -- --urls http://localhost:5000

Leave this terminal running. Open a second PowerShell terminal for your first request.

Your first useful result

Create a Todo, then read it back:

Invoke-RestMethod -Method Post -Uri http://localhost:5000/api/todos -ContentType application/json -Body '{"title":"Ship something useful"}' Invoke-RestMethod http://localhost:5000/api/todos

Stop the app with Ctrl+C, run it again, and repeat the GET. Your Todo is still there.

Let the same application grow.

A new requirement adds capability around the Entity you already know. Keep the business change small and the setup visible.

01

Search by meaning

Once Entity embedding integration, an embedding model, and a vector store are composed, search uses the Entity’s vocabulary:

Entity search

var matches = await Todo.Ai.Search(
    "something quick to finish before lunch",
    search => search.Top(5));

View this source excerpt →

The application keeps saying Todo. Choose the fields that define similarity, and use the same model for stored and query embeddings.

What this capability needs

Add Entity embedding integration and a model provider. Declare an embedding over Title, select an embedding model, and choose the index. Ollama runs as a local service; ONNX runs in-process. A durable SqliteVec index survives restarts. Model files still need to be obtained.

Complete installation, code, and verification →

02

Let agents reach the same Todo

Add the MCP capability, then declare which Entity is visible:

Package reference

dotnet add package Sylin.Koan.Mcp

On the existing Todo class

[McpEntity(Name = "Todo", Description = "Work the team intends to finish")]

View this source excerpt →

The existing model gains an agent-facing doorway. The declaration selects it; your access rules determine what callers may do.

Choose transport and access

Import Koan.Mcp, choose local STDIO or explicitly enable Streamable HTTP, and configure caller permissions. Verify an allowed operation and a denied operation through the selected transport.

Complete MCP setup and boundaries →

These are focused excerpts. The linked recipes own the complete setup, provider choices, and behavior checks.

Shared expertise, working software

One foundation. Two applications.

Your team’s decisions can travel with its code. Package approved capabilities, shared contracts, and business policy. Each application builds its own workflow on that foundation.

Example.Approvals.Foundation

Common approval fields, a spending limit, lifecycle policy, and guidance shipped together in one NuGet package.

ApprovalDesk

A supplier request becomes a recorded purchase order. This application owns suppliers, cost centers, and order references.

ExpenseDesk

An employee receipt becomes a reimbursement record. This application owns employees, receipts, and reimbursement references.

Architects and domain engineers shape the shared contracts and policy. Feature developers own each application’s next requirement. New contributors and coding agents have the same code, guidance, and examples to work from.

Explore the verified policy update

This is a recorded application experiment. Both desks consumed the foundation as a NuGet package; all Koan dependencies came from nuget.org.

One shared policy update, observed in both applications
Action	Foundation 1.0.1 · USD 1,000	Foundation 1.0.2 · USD 500
Approve a new USD 750 request	Allowed in both desks	Rejected in both; request stays pending
Approve through MCP	The same spending limit applies	The tighter limit applies here too
Read a completed order or reimbursement	The recorded result is available	The original result is preserved
Finish a USD 750 request approved before the update	Ready for its business action	Its earlier approval can still complete

168 checks passed across both consumers, the policy update, and an isolated rollback. Consumer business source stayed unchanged between package versions.

The package versions are controlled local experiment history. These apps demonstrate business policy and recorded outcomes; identity, tenant isolation, and external order or payment delivery need their own implementation.

Bundles select capabilities. Modules and application boundaries enforce rules. Your organization owns the foundation’s extension points and compatibility promises.

Run both applications →Inspect the update and rollback evidence →

Work with an agent. Let an agent work with your app.

Two useful paths, with different jobs.

Build, change, and explain

Koan’s coding skills direct an agent to the application, exact capability guidance, and a working recipe. It can add a feature, repair behavior, explain a provider choice, or plan a framework upgrade.

Read https://sylin.org/koan/llms.txt and the instructions in this project. Add semantic search over Todo titles. Preserve the existing HTTP routes. Show the required packages, model and storage choices, then verify the behavior.

The web template includes agent guidance. The install guide covers supported skills and portable instructions for other harnesses.

Set up Koan’s agent workflows →Read the focused agent index →

Use application operations through MCP

Reference Koan’s MCP package and select the Entities to expose. Agents can discover and use application operations through the same configured Entity access rules and persistence policies.

Choose the transport and caller permissions explicitly. Local STDIO and remote Streamable HTTP serve different needs; remote access needs its authentication configuration.

Expose an application through MCP →

Understand what joined the application

Package references → AddKoan() → application capabilities

koan.lock.json records build-time composition. Startup output and /.well-known/Koan/facts explain runtime decisions. Health endpoints report liveness and dependency readiness. An agent can read the corresponding facts through koan://facts.

Where it stands today

Koan’s 1.0 release train targets .NET 10. Packages publish independently under the Sylin.Koan.* family, with capability-specific maturity and operating requirements.
The shared-foundation example is reproducible with published Koan dependencies. It establishes policy reuse across two applications; independent adoption and productivity measurements remain open work.
Local AI can use a separate model runtime or in-process ONNX. Choose the model, vector store, and operating profile through the semantic-search recipe. NativeAOT has a separate, composition-specific verification boundary.

Choose capabilities by outcome →Find a working recipe →Check capability maturity →Read the NativeAOT boundary →

Build an application Work with an agent Create a shared foundation

Local connectivity substrate

A minute with Koi

01

On your workstation

See the databases, development servers, containers and devices already around you, then give the ones that matter names that survive the next restart.

02

Across your homelab

Let native applications, containers and physical devices participate in the same local network without rebuilding the stack around a new control plane.

03

Inside a private fleet

Give people, scripts and agents one current picture of what can be found, trusted and reached.

Start by looking

Before Koi asks you to shape the network, let it answer one useful question: what is already here? Install the v1 release candidate for your platform, then look.

Linux or macOS

$ curl -fsSL https://raw.githubusercontent.com/sylin-org/koi/v1.0.0-rc.2/install.sh | KOI_VERSION=v1.0.0-rc.2 sh

Installs the current v1 candidate from its release archive and verifies the checksum.

Windows PowerShell

$ $env:KOI_VERSION='v1.0.0-rc.2'; irm https://raw.githubusercontent.com/sylin-org/koi/v1.0.0-rc.2/install.ps1 | iex

Uses the same pinned, checksum-verified release contract on Windows.

Now ask the network

Browse the local network now:

koi mdns discover

Discovery runs on its own. If the result earns a permanent place, keep Koi running and add useful names, trust and deeper connectivity in the order your network needs them.

Find. Trust. Connect.

Three outcomes, carried by one living view of the local environment. Use the part you need first; let the rest join as the network grows into it.

◆Find

Discover services over mDNS and DNS-SD, see containers as they arrive, and give local things useful .internal names. Lifecycle events keep the picture moving with the network.

◆Trust

Give local names and peers shared identity through a private certificate mesh, guided enrollment, native trust-store integration, renewal and diagnosis.

◆Connect

Let containers, host applications, devices, proxies, resolvers, monitors and agents participate through the interfaces that already make sense to them.

One service, from arrival to conversation

service appears  ->  found by a useful name  ->  trusted where needed  ->  connected across its boundary  ->  removed when it leaves

The same lifecycle is visible through the CLI, dashboard, APIs and MCP, so people, applications and agents are talking about the same network.

What it looks like from where you sit

For the builder

Describe what a service offers once. Koi carries discovery, naming and participation across operating systems and runtime boundaries.

For the operator

See arrivals, health, restarts and departures through one coherent local story while keeping the DNS, proxy and monitoring tools already in place.

For the agent

Begin with current environmental context instead of spending the first exchange probing ports, reading stale host files and guessing what is still alive.

Meet the v1 release candidate →Read why Koi exists →See the physical-network evidence →Code signing policy →

See what's here Explore Koi Read the v1 RC docs

Reach for Ghostlight when

The job needs a site where you are already signed in.
You want browser work to stay visible and interruptible.
Several page states, tabs, forms or evidence sources belong to one workflow.

Responsible browser automation

A minute with Ghostlight

01

Work where you are signed in

Use the Chromium profile that already has the session the job needs, without copying credentials into a separate browser service.

02

Watch and take over

The agent works in a dedicated visible tab group. Pause, interrupt, or use the browser yourself whenever you need to.

03

Pick up where the browser left off

Exact workspace identity and useful next steps help work survive ordinary page, tab, and connection changes -- and repeat work reuses the tab group and tab it already owns instead of littering the strip.

Useful first. Responsible all the way through.

Ghostlight starts with the job: see the page, act in the browser, and return a compact result. Visibility, boundaries, and evidence belong to that same experience.

◆The browser where your work lives

Act in signed-in Chromium: navigate, fill forms, manage tabs, and read pages as structure or text.

◆A boundary you can understand

Begin wide open. When needed, enforce scopes, protect domains, explain denials, and record every call locally.

◆A system you can keep

The MCP connector, Rust service, browser connector, and extension run locally. The engine is open, governance is readable, and nothing phones home.

Local by construction

MCP client  <->  ghostlight-mcp-connector  <->  ghostlight orchestrator  <->  ghostlight-browser-connector  <->  extension  <->  Chromium

The orchestrator, connectors, and extension run locally as the current user. No Ghostlight-hosted control plane sits in the runtime path.

What it looks like from where you sit

For you

One installer and visible, interruptible work.

For the agent

Stable schemas, compact results, and useful recovery guidance.

For your scripts

One command installs; repeat installs change nothing; doctor --json and preserved exit statuses make the CLI safe to automate against.

For the organization

Policy a person can read: one line per capability naming the layer that decided it, signed bundles from your own source, stable denial ids, and a local audit record that never leaves the machine.

Try it for real

Let your agent handle setup, or run the installer yourself. Both paths end at the same doctor check.

Let your agent install it

Copy the install prompt

It reads the canonical guide instead of guessing at client setup.

Prefer the terminal?

$ npx -y ghostlight install

Check the whole chain

$ npx -y ghostlight doctor

Doctor names anything missing.

Your first safe job

Open https://example.com/ in a new Ghostlight tab, summarize the page, and tell me which tab you used. Do not click, type, submit, or change the page.

You should see a dedicated Ghostlight tab group, the exact tab used, and a summary produced without a click, form write, or page change.

Try the fit, not a feature list

5 ways to try it

Start with the read-only check above. These five bounded recipes show the other jobs Ghostlight is built to carry without turning the page into a tool catalog.

01 Complete a safe launch briefSynthetic form work

Prompt

Open https://sylin.org/ghostlight/demo/brief/ in a new Ghostlight tab. This is a simulated form. Set Project to Moonlight Notes, Owner to Maya Chen, and Summary to "Turn field observations into a shared release brief." Enable Include screenshots and Keep data local, then select Create brief. Stop when the page confirms the brief is ready for review.

What you should see

A visible read, deliberate field changes, one submit action, and "Moonlight Notes is ready for review."

Success boundary

Only the synthetic Sylin demo changes. Nothing is sent or stored.

02 Read authenticated work without copying credentialsUser-chosen signed-in page

Prompt

Open [SIGNED-IN APPLICATION URL] in a new Ghostlight tab using my current browser session. Confirm the account or workspace name visible on the page, summarize the current page, and list the next available actions. Do not click, type, submit, or copy credentials.

What you should see

The chosen application opens with the browser profile session, and the answer reports visible context without changing the page.

Success boundary

The person chooses and confirms the account. Do not record or quote the result without permission.

03 Follow one exact browser-created childTab continuity

Prompt

Open https://example.com/ in a new Ghostlight tab. Add a temporary link labeled Open child proof that points to https://example.org/ and opens in a new tab, then click that link. Follow the browser-created child and report the title and URL of both the original and child tabs. Do not close either tab or change either site.

What you should see

One exact child becomes usable without a manual context refresh, while the source tab stays open.

Success boundary

The temporary DOM change stays in the disposable example.com tab. Ambiguous popups are refused rather than adopted.

04 Combine page, console, and network evidenceRead-only diagnosis

Prompt

Open https://sylin.org/ghostlight/demo/foundry/ in a new Ghostlight tab. Start console and network tracking, reload once so page-load events are captured, then inspect the page, console, and network buffers. Report any failed request or console error, distinguish observed evidence from inference, and recommend one next check. Do not modify the page.

What you should see

The answer separates page state, browser events, and inference. Finding no error is a valid result when the evidence is clean.

Success boundary

The single reload is explicit because console and network tracking begins when first requested.

05 Continue a task without littering the tab stripTab and group reuse

Prompt

Open https://example.com/ in a new Ghostlight tab and summarize the page. Then open it again and summarize it once more. Report which tab handled each request. Do not close any tab or change any site.

What you should see

The first open creates or adopts one Ghostlight tab; the second open reuses it. The summary says the same tab handled both, and no duplicate example.com tabs appear.

Success boundary

Only the disposable example.com tab is touched. A tab you moved or pinned yourself is left where you put it.

Where it stands today

Ghostlight 1.0.0 is published: the orchestrator, MCP connector, browser connector, and the reviewed 1.0.0 store adapter. Windows and Linux are the supported platforms; the Chrome Web Store listing serves the 1.0.0 adapter, which covers Ghostlight 1.0.x. See the compatibility map for adapter and service version pairings.
Windows and Linux are the supported operating systems and are verified end to end against live browsers.
The Chrome Web Store serves Chrome adapter v1.1.4. Compatibility is recorded in compatibility.json. Install the extension from the public listing.

Browser-control decision aid →Safe demo space →Open Trust Center →How it compares →

Try the safe demo Compare browser-control approaches View the source

Reach for Zen Garden when

You have thin clients, retired PCs or other capable machines that should be useful instead of becoming e-waste.
You want a handful of self-hosted services without hand-maintaining container commands, ports and hostnames.
You value local ownership, comprehensible infrastructure and the freedom to replace individual machines.

Regenerative local infrastructure

A minute with Zen Garden

01

Prepare a Stone

Boot the garden installer on a spare machine. It receives a name, an identity and a place in the garden.

02

Offer what you need

Name the service. A checked-in manifest carries the operational knowledge for selecting, placing and starting it.

03

Find it by meaning

Ask for MongoDB, not a remembered box. Rake returns the current location and a connection URI for people, scripts or agents.

A garden in the wild

Useful machines, working together.

An operational Zen Garden on a workbench, with repurposed Dell thin clients, illuminated companion displays and a central status screen. — An operational Zen Garden test environment: repurposed thin clients and mixed hardware working as named Stones, with central status reporting and illuminated companions making the garden visible at a glance.

Useful hardware, tended as one garden.

Zen Garden starts with service intent, then carries that intent through placement, operation and discovery. The container is disposable; the offering name, configuration, data location, port and discoverability are what the garden remembers.

◆Machines become Stones

Retired PCs, thin clients and Raspberry Pis become named participants instead of e-waste. The garden is designed around replaceable hardware, not precious servers.

◆Services become offerings

A curated manifest expresses how a service should run. Moss negotiates hardware, storage and ports, then keeps the resulting runtime aligned with that intent.

◆Locations become answers

Applications and people ask for a service by what it is. Discovery supplies its current URI, and Koan can carry that intent as a zengarden:// resource.

What's inside

Curated offerings 51 checked-in service templates spanning databases, AI, networking, storage and more

Hardware negotiation compatibility, preferences, GPU capabilities and image fallbacks inform placement

Durable service intent persistent data paths and remembered ports survive managed-container recreation

Three service modes manage a Zen container, observe an existing service or publish an external one

Operational surfaces health, resources, logs, events, lifecycle commands and the Pulse terminal

Physical companions Cricket audio and Firefly displays give each Stone a voice in the room

Intent becomes infrastructure

spare machine -> named Stone -> offer manifest -> Moss -> running service -> connection URI

Moss tends the runtime on each Stone. Rake, scripts and agents inspect the same garden; Koan applications can resolve zengarden:// resources into current connection strings.

What it looks like from where you sit

For the builder

One service-shaped request replaces a page of container, storage, port and discovery plumbing.

For the agent

Compact commands plus JSON and URI output keep infrastructure work legible and composable.

For the operator

Pulse, health, events, logs and visible companions make the garden observable in software and in the room.

For the inheritor

Named offerings and checked-in manifests preserve why a service exists after its original machine is gone.

Grow one useful thing

Once a Stone is running Moss, two commands turn service intent into something an application can use.

Ask the garden for MongoDB

$ garden-rake offer mongodb

Zen Garden evaluates the offering and hardware, creates durable storage, negotiates a usable port and starts the managed runtime.

Receive its connection URI

$ garden-rake find mongodb --format uri

Discovery returns where the service is now, without making the application remember which Stone hosts it.

Then watch the garden tend

Open the live terminal view when you want the whole garden in sight:

garden-rake pulse

Pulse makes Stones, offerings and current state visible without turning ordinary service use into an operations dashboard.

Where it stands today

The offering lifecycle, discovery, operations and companion surfaces all run on a real mixed-hardware garden, and you can test them from source.
The USB creator builds an unattended Stone installer today. A signed turnkey image is still on my list.
Moss can rebuild a missing managed container on a surviving Stone. Cross-Stone state recovery, guarded update rollback and real high availability are what I am working on next.

Prepare a first Stone →Inspect the offering lifecycle →Meet the companions →

Grow the first service View the source

Reach for Suzu when

You want one physical notification you will actually feel - on a shelf, not in a tray.
You have a spare board - a matrix, an OLED - and ten minutes.
You want your scripts, cron jobs, or agents to ring a bell instead of writing another log line.

Software, with a body

A minute with Suzu

01

Meet the fleet

suzu scan introduces every plugged-in board in plain words: who is new, who is silent, who already speaks suzu. No guesses.

02

Adopt a face

suzu prepare backs the board up, installs the face you picked, reads everything back to make sure, and remembers who it is. If it ever leaves, suzu restore sends it home unchanged.

03

Let it live

suzu serve settles the Resident in as a service - Windows, Linux, systemd or OpenRC - and the house gets a window: open any browser to the workbench and watch the faces breathe.

A face has a mood. Events are weather.

Each face rests on a calm background - working, resting, gone. Moments land on top like raindrops and fade. When something is urgent it breathes faster; nothing ever shouts.

◆Weather, not alarms

A face rests in a calm mood and moments fall on it like rain. State is quiet; events pass. You glance, you know, you go back to what you were doing.

◆Urgency is tempo, not volume

When something needs you, its face breathes faster. Nothing flashes red and demands. A house that shouts gets ignored; a house that breathes gets watched.

◆Worst part wins

Nine healthy disks and one dying one: the face shows the dying one. The room hears the truth of the machine, never its average.

What's inside

The Resident suzu serve - one small service minding host sensing, device sessions, moments, and publishing, picking itself back up when it trips

The suzu/1 contract one versioned language for faces and moments, whatever is doing the knocking

Adoption with receipts suzu prepare - backup first, read-back verification, the board keeps its name

It installs itself sudo suzu install deploys the binary, its resources, udev, and the right service file - systemd or OpenRC

In-band optics suzu screenshot and suzu record - frame grabs and GIFs straight off the wire, no reboots

Faceplates a face's wardrobe, declared in faceplate.yaml; numerals and slate ship today

One small door, many knockers

anything that can POST -> the Resident -> faces on the wire

Cron, CI, your own scripts, an agent - they all knock the same way. The Resident keeps the one versioned language the faces speak, so nothing on your desk needs to know where a moment came from.

What it looks like from where you sit

For the household

The backup finished and the shelf turned green. The disk is dying and something said so, once, softly. You look up less, and miss less.

For the builder

Three verbs: scan, prepare, serve. Every install is backed up first and verified after. The tool that could brick a board is the same tool that un-bricks it.

For the agent

One POST with a signal and a label rings the whole fleet. The bell is documented, versioned, and waiting for your runner.

For the inheritor

The board keeps its old firmware and its name. Change your mind and suzu restore puts everything back the way it was.

Wake one face

Two commands and one confirmation. You will know it worked because the board lights up.

See who is plugged in

$ cargo run -- scan

Every port named in plain words - NEW, fresh firmware, unreachable - joined with the hardware catalog.

Adopt it

$ cargo run -- prepare

Pick the device, pick a faceplate, confirm. Backup first, verification after, device_id preserved.

Then ring the bell by hand

Put the Resident on duty and send it one moment:

cargo run -- say completion A backup committed

The face splashes the moment, then settles. From then on it just knows - and any browser on the host opens the workbench.

Where it stands today

Two faces live on real hardware: the RP2040 matrix and the ESP8266 dual-zone OLED, speaking the versioned suzu/1 wire language.
The Resident runs as a service on Windows and on three Linux testbeds - Arch, Fedora Atomic, Alpine - installing itself with one command and serving the workbench to any browser.
Factory-fresh ESP8266 boards onboard end to end, in Rust, with no other tooling; Cricket, the audio companion, and the further transports wait their turn.

Read the contract →Why the matrix is a lake →The installation incident →How onboarding is proven →

Wake one face View the source

The pillars

◆Files are truth; the desk is a lens

The article is a plain Markdown file with a small meta.yaml sidecar. Indexes, journals, previews and renditions are derived caches the desk rebuilds from files at every open - delete the application and lose nothing you wrote.

◆One grammar of change

Every mutation flows the same path: an atomic write plus a journal entry, with review before anything irreversible. The per-article journal answers what the app ever did to your files.

◆Saving never publishes

Saving touches nothing but files. Publishing reviews changed paths, commits only the selected ones, and pushes only while the reviewed remote state still holds.

What's inside

Document-first editor autosave over plain Markdown articles, with unmodeled content preserved verbatim in meta.yaml

Content-addressed media paste or drop an image and it lands as processed media with a correct relative link; renditions are declared intent, derived on demand

Advisory consult named verbs through your own assistant harnesses; results arrive as diffs you accept hunk by hunk

Ship pipeline with gates proof against the site's own build on a disposable copy, review scaled to stakes, lease-checked pushes

The desk a per-publication index rebuilt from files whenever the publication opens, with last-opened memory

The tezuri CLI the same domain library from a terminal: cargo run -p tezuri -- desk

Get started

# installs the locked frontend dependencies, builds the bundle on first use, then opens the desk (Rust and Node 20+ expected)

$ launch.bat

# build the interface bundle, then start the desktop shell

$ npm --prefix src-tauri/ui ci && npm --prefix src-tauri/ui run build && cargo run --release -p tezuri-desktop

Reach for it when

Your articles should outlive the tool that writes them · images should stop being mechanical misery · the destination repository's own build should stay the referee · you are comfortable building from source while installers are on the way.

Reach for Agyo when

A Koan application needs an advanced capability without a parallel bootstrap, domain model or provider vocabulary.
A small application should gain something substantial without letting integration plumbing dominate its code.
Optional dependencies and their security cadence should remain outside Koan core until an application asks for them.

Optional capability layer

A minute with Agyo

01

Name the capability

The reference says what the application needs. Agyo carries the recurring registration, lifecycle and provider mechanics.

02

Keep one application

Entities, hooks, configuration and business behavior stay in Koan's familiar grammar instead of splitting into another integration layer.

03

See what joined

Capabilities participate in Koan's startup and operational vocabulary, so optional composition can remain inspectable.

Capability without a second architecture.

Agyo is where useful Koan-native capabilities can grow independently. Applications reference only what they need; the foundation stays lean and the resulting system stays recognizable.

◆Only when you ask

GraphQL, RAG, Vault, PGVector and other dependencies stay outside Koan core. The application references only the capability its next use case earns.

◆The same application grammar

Agyo joins AddKoan(), entities, hooks, configuration, health and startup reporting instead of creating another framework beside the application.

◆Independent by design

The one-way package boundary keeps Koan lean while optional capabilities move on the dependency, security and release cadence their job requires.

What's inside

Application interfaces GraphQL over Koan entities and duplex WebSockets exposed as .NET Streams

Application capabilities in-process scheduling, AI translation, canonical tagging and an OpenTelemetry baseline

Infrastructure adapters PostgreSQL pgvector search plus environment, configuration and HashiCorp Vault secret resolution

Intelligence toolkit RAG ingestion, provenance, retrieval, concept graphs, distillation, evaluation and corpus composition

Built with Agyo Librarian turns local repositories into cited code and documentation context over REST, UI and MCP

One application, optional reach

Koan application + chosen Agyo capability -> AddKoan() -> one composed runtime

Agyo depends on Koan's public packages; Koan never depends on Agyo. That one-way boundary keeps every capability optional and gives it an independent release and security cadence.

What it looks like from where you sit

For the developer

The capability arrives; the code you are left reading is still about your application.

For the agent

A known package and one composition grammar, in place of invented wiring.

For DevOps

Visible dependencies, health and provider choices, with defaults that are safe to ship.

For the architect

A controlled frontier that lets Koan stay coherent instead of growing into a monolith.

Follow Agyo toward V1

The capability source works and is testable today. Published packages and compatibility guarantees are part of the V1 work.

Explore the current source

$ git clone --branch dev https://github.com/sylin-org/agyo-tools

The repository contains the libraries, focused tests, decisions and live surface ledger. Building currently requires compatible Koan packages in its local feed.

The V1 first result

Reference one published capability in an existing Koan app and run it through the same AddKoan() composition. GraphQL is the clearest target: existing entities gain /graphql and /graphql/sdl without a second domain model.

Where it stands today

Twelve library projects pack from source, the principal composition paths have focused tests, and Librarian is a substantial runnable service assembled entirely from Agyo capabilities.
There is no NuGet release yet - the first Sylin.Agyo.* packages and a clean package-first path in are part of the V1 work. Follow the source if you want to track it; package IDs and APIs are open until that release.
Some boundaries are deliberate: scheduling stays in-process, GraphQL typing is still limited, the AI, vector and Vault paths need their providers running, and the full tool-using RAG loop is still ahead of me.

Read the Agyo charter →Inspect the surface ledger →Trace the current tests →

View the current source Read the architecture decisions

Reach for Shiguchi when

You build agents, hosts or workflows that should survive a change of provider without learning another tool dialect.
You publish an agent-facing capability and want a checkable contract rather than a self-described compatibility badge.
You need to adapt an existing server once, review the mapping and make every approximation or gap visible.

Capability Class Profiles

A minute with Shiguchi

01

Speak the capability

An agent targets an exact semantic identity such as calendar create-event instead of carrying every vendor's spelling and schema in working memory.

02

Know the claim

A compatibility statement names the exact profile, baseline, facets and fixture digest it passed. Prose can explain the contract; fixtures decide it.

03

Keep the ceiling

A frozen projection can welcome an existing server while its coverage manifest and passthrough surface preserve what the shared profile cannot express.

The joint holds because the shapes agree.

Shiguchi standardizes the small semantic surface agents can rely on, defines the behavior both sides must prove and leaves vendor-specific reach visible instead of sanding it away.

◆Profiles name the joint

An immutable Core baseline defines the capability's dependable floor. Optional facets add coherent jobs; namespaced Vendor fields preserve provider-specific reach with an explicit degradation story.

◆Fixtures prove the fit

Every conformance claim points to an exact suite and digest. Implementations and consumers must be tested through the same public MCP surface, so compatibility is observable rather than ceremonial.

◆Projection welcomes what exists

A model may draft a mapping once, but runtime meaning never depends on fresh inference. The reviewed capsule is frozen, upstream-pinned, behaviorally tested and paired with complete coverage disclosure.

What's inside

Calendar reference profile six baseline verbs, optional facets, an agent skill and adversarial Core fixtures

Operator draft profile a compact action surface, optional jobs, Core and facet fixtures, and a Vendor example

Normative semantic layer profile identity, descriptors, conformance, projection, kernel, facets and composite servers

Brownfield adoption path binding capsules, frozen mappings, coverage manifests and complete passthrough

Agent-readable adoption guides focused paths for operating, building, wrapping and authoring profiles

Open stewardship Apache-2.0 normative artifacts, neutral class namespace and a multi-party governance trigger

One capability, from arrival to use

capability appears  ->  exact class + baseline + facets  ->  native or frozen projection  ->  fixture-backed claim  ->  agent uses one known interface

Capability Class Profiles add semantics, not another transport. Profile verbs remain ordinary MCP tools, so an unaware client can still call them while a profile-aware client can select and verify the exact contract.

What it looks like from where you sit

For the builder

One contract per capability class replaces one integration grammar per vendor, while exact versions keep old workflows intelligible.

For the agent

A small vocabulary, canonical examples and stable schemas put more task intent in each token and make the next action easier to verify.

For the publisher

Native support or a reviewed projection creates a precise adoption path; coverage shows where the provider exceeds or falls short of the shared contract.

For the ecosystem

Apache-2.0 contracts, a neutral namespace and a written transfer path keep the shared language open beyond its first steward.

Start with a contract you can inspect

Shiguchi is specification-first today. The useful first result is understanding one complete agent-facing contract and seeing the behavioral cases that define it.

Clone the draft source

$ git clone https://github.com/sylin-org/shiguchi

The repository contains the normative specification, profile JSON, model-facing skills, fixtures, governance and adoption guides.

Read the calendar skill

$ cat shiguchi/profiles/calendar/SKILL.md

This self-contained view is what an agent needs to operate any server that eventually proves the exact calendar contract.

See how prose becomes proof

Now inspect the corresponding behavioral scenarios:

cat shiguchi/profiles/calendar/fixtures/core.fixtures.json

The fixtures make patch preservation, cancellation tombstones, free-time correctness and loud unknown-ID failures concrete. The runner that will execute them is still unbuilt.

Where it stands today

Draft 0.2. The normative concepts, descriptor, conformance, projection, kernel, facet and composite documents are all written - as drafts, not published baselines, so none carries a conformance digest yet.
Calendar is the worked reference profile, with JSON, an agent skill and a Core fixture suite. Operator has a draft contract, skill, Core and facet fixtures, and a Ghostlight-derived Vendor example. Neither has an independent implementation passing yet.
The reference runner, wrapper and playground are specified but unbuilt. Commands like shiguchi test and shiguchi wrap describe where this is heading, not something you can install today.
Most catalog classes are still sketches without fixtures. I am proving the runner and the validation slice before growing the catalog any further.

Read the core concepts →Inspect the calendar profile →See how conformance is judged →Follow an existing server through projection →Challenge the prior-art claim →

Start with the calendar profile Read the manifesto Explore Shiguchi

The concept

The OS stands for Operational Symmetry. Most cross-platform libraries copy one platform's shape onto the others; os-tools writes a mirror for each instead - structurally symmetric, mechanically alien - and fills the missing corners one crate at a time. Today it is a family of one.

What's inside

os-truststore install or remove a root CA in the OS trust store - the symmetric writer the ecosystem was missing

Symmetric API the cert is the identity: install, is_installed, uninstall - idempotent, and it never panics

Three real backends Windows CryptoAPI, macOS Keychain, and a Linux update-ca / p11-kit orchestrator

In-process trust an optional rustls feature builds a root store with no OS changes and no elevation

The concept

Hokora tries to model how a mind turns experience into understanding - consolidation during sleep, emotion tagged at the moment of encoding, a theory of mind that recurses - drawing its structure from neuroscience rather than from information retrieval. This repository is only the canon: every claim must trace to a real citation, and the software that would run it is deliberately elsewhere.

The concept

Nagi inverts the breathing app: the screen is the afterthought. The intended experience is a phone held to your chest, eyes closed, that you feel and hear breathe until your own breath falls into step with it - one semantic model of a single breath driving visuals, sound and haptics that never talk to each other yet stay perfectly in tune.

Koan

Koi

Ghostlight

Zen Garden

Suzu

Tezuri

Agyo

os-tools

Hokora

Nagi

A model. A route. A working API.

Make something you can keep.

Create and run

Let the same application grow.

Search by meaning

Let agents reach the same Todo

One foundation. Two applications.

ApprovalDesk

ExpenseDesk

Work with an agent. Let an agent work with your app.

Build, change, and explain

Use application operations through MCP

Where it stands today

A minute with Koi

On your workstation

Across your homelab

Inside a private fleet

Start by looking

Linux or macOS

Windows PowerShell

Find. Trust. Connect.

What it looks like from where you sit

For the builder

For the operator

For the agent

A minute with Ghostlight

Work where you are signed in

Watch and take over

Pick up where the browser left off

Useful first. Responsible all the way through.

What it looks like from where you sit

For you

For the agent

For your scripts

For the organization

Try it for real

Let your agent install it

Prefer the terminal?

Check the whole chain

5 ways to try it

Prompt

What you should see

Success boundary

Prompt

What you should see

Success boundary

Prompt

What you should see

Success boundary

Prompt

What you should see

Success boundary

Prompt

What you should see

Success boundary

Where it stands today

A minute with Zen Garden

Prepare a Stone

Offer what you need

Find it by meaning

Useful machines, working together.

Useful hardware, tended as one garden.

What's inside

What it looks like from where you sit

For the builder

For the agent

For the operator

For the inheritor

Grow one useful thing