# Rusl Agent Guide

Rusl is the shared contract layer for JSON Schema-based data contracts.
Before inventing a boundary-crossing payload shape, query Rusl for an existing
schema, bundle, annotation type, annotation, example, source attestation, usage
signal, review thread, or semantic link.

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

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

## 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/concepts`, `/d/getting-started`,
  `/d/tools`, `/d/config`, and `/d/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:

- CLI and login: `/d/getting-started#cli`
- Claude Code Agent Kit: `/d/getting-started#agent-kit`
- Project manifest and lockfile: `/d/config`
- MCP server setup and tool groups: `/d/mcp`
- Generator and validator recipes: `/d/tools`

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
- `.rusl/schemas`: default local install directory
- `rusl.config.toml`: optional schema output configuration

## 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.

Example `rusl.bundle.toml`:

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

## Core Objects

- Schemas: reusable JSON Schema-based contracts.
- Schema versions: immutable published release targets.
- Bundles: versioned packages of schema dependencies.
- Annotation types: schemas for kinds of semantic data.
- Annotations: typed semantic records attached to a Rusl subject.
- Accounts and groups: ownership, visibility, access, and collaboration
  context.
- Proposals and review threads: shared contract change workflow.
- 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 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 contracts.
3. Resolve the contract, 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.

- `rusl/annotation-types/context-loading-hint`: what context to load before
  using a contract
- `rusl/annotation-types/usage-report`: where a contract was used
- `rusl/annotation-types/domain-interpretation`: what a schema, field, or
  contract means
- `rusl/annotation-types/semantic-link`: graph edge to related contracts,
  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 contract 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 contracts: do not merge silently. Rank by identifier,
  publisher, version, bundle membership, annotation quality, source
  attestation, usage evidence, and domain fit.
- Conflicting annotations: do not invent global precedence. Prefer the
  annotation type's policy if known; otherwise surface the conflict.
- 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/concepts`
- `/d/getting-started`
- `/d/config`
- `/d/mcp`
- `/d/tools`
- `/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.
- 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 global annotation precedence.
- 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.