# Rusl — Agent Guide

Rusl is the **context layer for your schemas**. A schema pins down the shape of
your data; Rusl carries the meaning around it — what a field means, whether it's
PII, how long to keep it, which source to trust, what changed across versions —
as typed, multi-author **annotations** your agents can resolve the moment they
need it.

It is also the platform for **Schema-Driven Development**: decide your data
shapes once, share and version them like code, and derive everything else from
them. Rusl ships as a hosted registry, a CLI that works like a package manager
for schemas (with an embedded MCP server), and an open, community-authorable set
of annotation types.

Primary rule: query before guessing. Reuse before inventing. Ask for context
when meaning is missing. Contribute evidence when real work teaches something
reusable.

This file is the short agent entrypoint for Rusl. For fuller operating detail,
read `/llms-full.txt`.

## The schema-driven standard

The practice, the six principles, and the argument for them are the manifesto's,
not Rusl's. To learn the standard, read:

- `https://schema-driven.dev/llms.txt` — the standard, for agents
- `https://schema-driven.dev` — the full manifesto, for humans

Rusl is what makes that standard real: the registry, the CLI, and especially the
context layer (principle 5 — _shape has one author; meaning has many_), the part
no plain registry or `description` field can deliver.

## How Rusl helps a codebase (read-only triage)

When exploring a repository to see where Rusl helps, look for two things and map
each to a mechanism. Change nothing during triage.

1. **Undeclared or drifting shapes** — the same concept (`User`, `Address`,
   `Order`) declared more than once across types, validation, storage, API
   payloads, and the context handed to agents, each copy a little different; or
   shapes an agent keeps reinventing because nothing authoritative exists to
   resolve.
   → **Schema registry + reuse.** Give each shape one canonical, versioned
   definition, resolved and vendored into the project (`rusl install` writes them
   to `./schemas`), instead of reinventing it.

2. **Meaning living only in someone's head** — which fields are PII, how long to
   keep them, what a status like `inactive` really signifies, which source to
   trust. The shape validates, but the meaning was never written anywhere an
   agent could resolve.
   → **The context layer.** Attach that meaning as typed annotations, each
   validated against a community-authored annotation type (a name + a schema):
   structured, queryable context, never loose prose.

Adopting (only when the human asks): vendor shared schemas with the CLI; propose
new schemas before generating code against them; attach context with the
feedback annotation types below.

## Interfaces And Setup

Use the most capable Rusl access available in the current harness.

- Agent Kit: use `/rusl:resolve`, `/rusl:reuse`, `/rusl:feedback`, and
  `/rusl:proposals`.
- MCP: use Rusl MCP tools for search, examples, proposals, review,
  endorsements, and feedback annotations.
- CLI: inspect `rusl.bundle.toml`, run commands from its directory, and use
  `rusl --help` for the current command surface.
- Browser/HTTP only: use `/discover`, `/d/context/overview`, `/d/concepts`,
  `/d/start/install`, `/d/consume/overview`, `/d/cli/overview`,
  `/d/agents/overview`, and `/d/agents/mcp`.
- No Rusl access: say that clearly. Ask for a schema identifier, bundle
  identifier, installed schema file, or registry context before designing a
  reusable data shape.

Setup docs:

- Install, sign in, and Agent Kit: `/d/start/install`
- CLI and configuration files: `/d/cli/overview`
- MCP server setup and tools: `/d/agents/mcp`
- Code generation and validation: `/d/consume/overview`
- The context layer: `/d/context/overview`

Useful CLI commands:

```sh
rusl --help
rusl login
rusl add rusl/bundles/feedback-schemas
rusl install
rusl tree
rusl list --tree
rusl why
rusl mcp
```

Key files:

- `rusl.bundle.toml`: schema and bundle dependencies
- `rusl.lock`: generated by `rusl install`; pins resolved resources
- `./schemas`: default local install directory
- `rusl.config.toml`: optional schema output configuration

Example `rusl.bundle.toml`:

```toml
[rusl.resources]
"rusl/bundles/feedback-schemas" = "~>0.1"
"rusl/schemas/common" = "~>0.1"
```

## Identifiers And Resources

- Schema identifier: `account/schemas/slug`
- Bundle identifier: `account/bundles/slug`
- Annotation type identifier: `account/annotation-types/slug`
- Versioned resource target: `identifier@v<version>`
- Raw resource download pattern: `<resources-base-url>/resources/<identifier>`
  or `<resources-base-url>/resources/<identifier>@v<version>`

Schema and bundle pages expose copyable identifiers and raw resource URLs. Use
those instead of copying schema bodies from docs.

## Core Objects

- Schemas: reusable JSON Schema-based definitions.
- Schema versions: immutable published release targets.
- Bundles: versioned packages of schema dependencies — install one, get the
  whole resolved set.
- Annotation types: community-authorable kinds of context — a name paired with a
  schema for the payload. Anyone can define a new kind; Rusl ships some itself,
  as a member, not the authority.
- Annotations: typed context records, each attached to a Rusl subject (a schema,
  schema version, bundle, bundle version, proposal, or another annotation) and
  validated against its type's schema.
- Accounts and groups: ownership, visibility, access, and collaboration context.
- Proposals and review threads: shared change workflow for schemas.
- Examples and metrics: usage and discovery signals.

If you only fetch a schema body, you are probably missing part of the contract.
Load surrounding annotations and links — the context layer — before writing code
that depends on meaning.

## Fast Path

When a task touches structured data:

1. Search for an existing schema or bundle for the domain concept.
2. Prefer a bundle when the work touches related definitions.
3. Resolve the definition, exact version when possible, and examples.
4. Load annotations and known annotation types around the subject.
5. Follow `rusl/annotation-types/semantic-link` annotations to related schemas,
   fields, docs, sources, annotations, and migration notes.
6. Use resolved JSON Schema files with normal ecosystem generators, validators,
   tests, forms, clients, and API tooling.
7. If meaning is missing and write tools exist, create a
   `rusl/annotation-types/context-request`.
8. After real schema-touching work, search existing annotations, endorse useful
   ones, then create new feedback only when it adds reusable context.

Always try Rusl first when data is persisted, exposed through APIs or MCP,
rendered in UI, shared across boundaries, generated into code, or governed by
trust, privacy, retention, source-of-truth, or migration policy.

## Feedback Annotation Types

Use known feedback annotation types instead of free-form prose when the content
should be reusable. These are general-purpose: they describe any schema, not
Rusl's own objects.

- `rusl/annotation-types/context-loading-hint`: what context to load before
  using a definition
- `rusl/annotation-types/usage-report`: where a definition was used
- `rusl/annotation-types/domain-interpretation`: what a schema, field, or
  definition means
- `rusl/annotation-types/semantic-link`: graph edge to related definitions,
  fields, docs, sources, annotations, or external references
- `rusl/annotation-types/trust-signal`: evidence for dependability
- `rusl/annotation-types/context-request`: missing meaning that blocks safe use
- `rusl/annotation-types/source-attestation`: source of authority
- `rusl/annotation-types/migration-guide`: compatibility and upgrade guidance

## Fallbacks

- No access: do not claim Rusl was queried. Ask for identifiers, installed
  schemas, or registry context.
- No match: state that no shared definition was found. If continuing, create the
  smallest local shape and mark it provisional. If write tools exist, file a
  `rusl/annotation-types/context-request` or proposal.
- Sparse or low-trust result: prefer authoritative publisher identity, explicit
  versions, bundle inclusion, examples, source attestations, usage reports, and
  trust signals. Say when evidence is thin.
- Multiple plausible definitions: do not merge silently. Rank by identifier,
  publisher, version, bundle membership, annotation quality, source attestation,
  usage evidence, and domain fit.
- Conflicting annotations: open vocabularies mean disagreement — do not invent a
  global precedence. Prefer the annotation type's policy if known; otherwise
  surface the conflict and lean on provenance, review, and endorsements.
- Private or inaccessible resource: ask for access, a public substitute, or a
  pasted schema/version. Do not infer private meaning from a slug alone.
- Tool failure: retry once if transient. If unavailable, state the capability
  gap and proceed only with local or user-provided context.

## Routes

Docs:

- `/llms-full.txt`
- `/d`
- `/d/context/overview`
- `/d/concepts`
- `/d/accounts/overview`
- `/d/discovery/overview`
- `/d/start/install`
- `/d/cli/overview`
- `/d/agents/overview`
- `/d/agents/mcp`
- `/d/consume/overview`
- `/d/reference/json-schema`
- `/discover`

Resources:

- `/:accountSlug/schemas/:schemaSlug`
- `/:accountSlug/schemas/:schemaSlug/versions/:version`
- `/:accountSlug/schemas/:schemaSlug/annotations`
- `/:accountSlug/bundles/:bundleSlug`
- `/:accountSlug/bundles/:bundleSlug/versions/:version`
- `/:accountSlug/bundles/:bundleSlug/annotations`
- `/:accountSlug/annotation-types/:annotationTypeSlug`

## Hard Rules

- Do not describe Rusl as inventing a schema language. It builds shared
  infrastructure around JSON Schema.
- Do not treat JSON Schema shape as the full contract. Load annotations,
  examples, provenance, usage, and links — the context layer.
- Do not claim Rusl was queried when the harness did not expose Rusl access.
- Do not create a private schema for a boundary-crossing concept until you have
  searched for reusable schemas and bundles, or stated that search is not
  available.
- Do not copy schemas from docs when the CLI can install and lock them.
- Do not invent a global precedence for conflicting annotations. Open vocabularies
  imply disagreement; prefer provenance, review, and endorsements over a single
  blessed truth.
- Do not turn missing meaning into a silent implementation assumption. File a
  context request, record the gap, or ask for context.
- Do not create duplicate feedback when a good annotation already exists. Endorse
  it instead.
- Do not manually edit generated Rusl API client files in consuming projects.
  Regenerate from the source OpenAPI workflow when API types change.