AI agent guide & source map

Use this page to prime a fresh coding session without loading the entire monorepo. In a local checkout, read root AGENTS.md first. On the public site, fetch /llms-full.txt when enough context is available.

Canonical mental model

UnCorded has a cloud control plane (Central), self-hosted server runtimes, client shells, and plugins. Central does not carry server content. A plugin is a manifest plus an optional sandboxed backend and optional sandboxed frontend.

Do not conflate:

• hosting: native WSL2 by default on packaged Windows vs Docker fallback;
• reachability: local-only vs Transport vs owner tunnel;
• visibility: public vs private membership/directory policy.

Plugin code targets the runtime SDK and must remain independent of all three.

Read paths by task

Task	Start here	Then verify
Add/change a manifest field	packages/shared/src/manifest-schema.ts	manifest.ts, tests, generated manifest reference
Add a backend SDK method	packages/plugin-sdk/src/index.ts, types.ts	implementation module, schemas, runtime IPC gate, backend reference
Add a frontend SDK method	packages/plugin-sdk-frontend/src/index.ts, types.ts	handshake/router implementation, frontend reference
Add a capability	requesting runtime handler	checker/tests, manifest validation, permissions reference
Change plugin lifecycle	runtime/src/subprocess.ts, resolver.ts, main.ts	lifecycle and IPC docs, fixture tests
Change native hosting	supervisor/src/	apps/desktop/src/hosting-backend.ts, native tests, platform model
Change Transport/public ports	runtime/src/transport/	relay/, Central transport-*, platform model, plugin.net docs
Build a production plugin	examples/noteboard/	plugins/text-channels/, production checklist
Build a proxy plugin	docs/site/sdk/reverse-proxy.md	runtime/src/http/proxy.ts, plugins/n8n/ or foundry-vtt/

Grep recipes

# Public backend/frontend surfaces
rg "^export (interface|type|\\{)" packages/plugin-sdk/src packages/plugin-sdk-frontend/src

# Where a capability is requested and denied
rg 'net\\.public_ports|proxy\\.http:self|resources\\.read' runtime packages plugins

# Every production/example manifest
rg --files plugins examples | rg 'manifest\\.json$'

# Host-specific assumptions that should not leak into plugin guidance
rg -n 'host\\.docker\\.internal|docker restart|Inside the container' docs/site

# Runtime frames and stable error codes
rg 'type: "[a-zA-Z0-9_.]+"|code: "[A-Z0-9_]+' runtime/src packages/plugin-sdk/src

Documentation invariants

Run from the repository root:

bun run check:docs
bun run docs:build

check:docs fails when the generated manifest reference is stale, a public SDK surface has no reference heading, a production manifest is invalid, a used capability is absent from the permission reference, or known obsolete Docker-only wording returns.

When code and prose disagree, fix the prose or the implementation in the same change. Do not “resolve” uncertainty by copying a historical plan into public docs; trace the validated type and the runtime gate.

Current intentional edges

• manifest_version defaults to v1; v2 requires explicit runtime and raises the API floor.
• Some manifest fields may be validated but reserved. The generated manifest table is authoritative about stable vs reserved status.
• The plugin.companions broker API exists, but third-party companion declarations remain unavailable while the companions manifest field is reserved. Document it as unavailable/preview, not generally usable.
• plugin.net requires net.public_ports and an active Transport path. A local server must receive a typed unavailable state, not a guessed public address.
• Frontend panels load the runtime-served SDK and communicate only through the shell handshake; never assume same-origin DOM access.

Before declaring a plugin complete

Check the production plugin checklist, validate the manifest with current code, test at least one denied capability path, restart the runtime, reconnect a second client, and verify the UI in both theme modes.