One document for the whole system.

Kageos is not an app generator whose job ends when a screen appears. It is a runtime and governance layer for useful capabilities. Those capabilities live as directories on a Service Tree, with stable paths, typed functions, UI resources, runtime state, and audit records.

A directory can start from Hub, run inside a private namespace, be changed for local data and workflow habits, and later be packaged again. The same capability can serve a single person, a small team, or an enterprise department because the boundary is the directory, not the chat session that created it.

AI makes it cheap to create software-shaped things. Production makes a different demand: the thing needs an address, a calling contract, permissions, logs, ownership, and a way for someone else to take over later.

A prompt result rarely gives you that. A directory can. In Kageos, the directory is where the work becomes durable enough for people, agents, schedules, and other directories to use.

Kageos treats a directory as a packaged workflow, not a folder of links. The platform gives the directory a path, renders its UI, calls its functions, runs its containers, schedules its jobs, and stores the trail left by each run.

There are three normal ways to use a directory. A person opens the page and works. AI reads the directory context and calls tools. A scheduled task runs without a person online, then writes the result back as messages, logs, and updated records.

That last part matters. Unattended automation is not a hidden cron script. The scheduler owns state. The executor only executes. The run has an identity, a source, a trace, and a place where the team can review what happened.

The public story should match the product. These are the capabilities already on the mainline, not future packaging language.

Contributors should start with kagectl. The Compose files are still in the repository, but they are implementation detail and troubleshooting material. A new contributor should not need to know the historical Compose paths just to boot Kageos.

Normal local startup does not require manual environment variables. kagectl bootstrap --dev creates local .kageos/ env files for MySQL, NATS, MinIO, JWT, SMTP log mode, and the system user password. Do not commit those files.

The codebase has two different kinds of code: the Kageos platform itself and workspace applications that run inside namespaces. Keep that boundary clean. Platform services can use internal packages. Workspace apps should use the public SDK, not main-repo internals.

Run the checks that match your change. The full list lives in the repository, but these are the checks maintainers expect contributors to know.

Kageos is source-available and designed for self-hosting. The current production path is a single-machine deployment with Kageos, MySQL, NATS, MinIO, and user app containers managed through the platform runtime.

The important operating idea is simple: platform state, app source, app runtime metadata, logs, and object storage are not throwaway build artifacts. Back them up before destructive resets. Keep secrets out of commits. Treat local .kageos/ and production .kageos/ as private runtime state.

Good documentation should say what is real and what is still planned. Kageos should not sell unfinished control planes as if they already exist.