# Koan

Koan is an opinionated .NET meta-framework for agentic, data-driven applications.
An Entity expresses business meaning. Package references express capability intent.
One AddKoan() composes the referenced modules.

This page routes to the framework's current guidance. Read the target application's
instructions first, then retrieve the linked guidance; do not reconstruct package names,
configuration keys, APIs, or operating guarantees from this summary.

## Build, extend, repair, explain, or upgrade an application

- [Portable agent bootstrap](https://github.com/sylin-org/koan-framework/blob/main/AGENTS.md): Application grammar, retrieval, and evidence.
- [Skill chooser and installation](https://github.com/sylin-org/koan-framework/blob/main/docs/guides/agent-skills.md): Coding, read-only explanation, framework migration, and adapter authoring workflows; portable sources for other harnesses.
- [Start an application](https://github.com/sylin-org/koan-framework/blob/main/docs/getting-started/quickstart.md): .NET 10 prerequisites and the published template journey.
- [Capabilities by outcome](https://github.com/sylin-org/koan-framework/blob/main/docs/capabilities/index.md): Begin here when the user describes a requirement.
- [Working recipes](https://github.com/sylin-org/koan-framework/blob/main/docs/recipes/index.md): Prerequisites, exact packages, configuration, code, costs, and verification.
- [Exact capability map](https://github.com/sylin-org/koan-framework/blob/main/docs/reference/capability-map.md): Direct lookup when the user already names a capability.
- [Evaluated product surface](https://github.com/sylin-org/koan-framework/blob/main/docs/reference/product-surface.md): Current claims, maturity, and evidence. Publication alone is not a capability guarantee.

## Let an outside agent use an application

- [MCP recipe](https://github.com/sylin-org/koan-framework/blob/main/docs/recipes/let-an-agent-use-my-app.md): Exposed Entities, transport, caller permissions, and allowed/denied operation checks.

MCP exposure selects the model. Access rules authorize operations. Preserve the application's
identity, tenant scope, and persistence policies; verify the chosen transport separately.

## Shared foundations

- [One foundation, two applications](https://github.com/sylin-org/koan-framework/tree/main/samples/applications/SharedApprovals): Purchase approvals and expense claims, common lifecycle policy, package consumption, and runnable verification.
- [Published-package evidence](https://github.com/sylin-org/koan-framework/blob/main/docs/initiatives/application-evolution/evidence/AE-01a.md): Policy tightening, persisted outcomes, HTTP/MCP behavior, and isolated rollback. This is technical reuse evidence, not an independent productivity study.

Bundles select capabilities. Modules and application boundaries enforce policy.
The organization owns shared contracts, extension points, and compatibility promises.

## Explain observed behavior

Read koan.lock.json for build-time composition, startup output and /.well-known/Koan/facts
for runtime decisions, and /health/live and /health/ready for health. koan://facts provides
the corresponding runtime evidence through MCP. State what the evidence proves and what is unknown.

- [Complete documentation index](https://github.com/sylin-org/koan-framework/blob/main/llms.txt)
- [Human product page](https://sylin.org/koan/)