# Solana Developer Platform

This file is the canonical agent guide for this repository.

## Repo layout

- `apps/sdp-api`: Node.js API deployed to Cloud Run, OpenAPI source, route handlers, Postgres/Redis integrations
- `apps/sdp-web`: dashboard application
- `apps/sdp-docs`: public documentation site and generated API reference
- `packages/sdp-types`: shared runtime types and shared product constants

## Source of truth

- Public API contract: `apps/sdp-api/src/openapi/**`
- Public docs navigation: `apps/sdp-docs/content/docs/meta.json`
- Generated API docs: `apps/sdp-docs/content/docs/reference/api/**`
- AI discovery resources: `apps/sdp-docs/public/llms.txt` and `apps/sdp-docs/public/llms-full.txt`

## Generated files

Do not hand-edit generated artifacts. Regenerate them with the owning script.

- OpenAPI JSON: `pnpm -C apps/sdp-api openapi:generate`
- API playground catalog: `pnpm generate:api-playground`
- API reference docs: `pnpm -C apps/sdp-docs generate:api`
- AI discovery resources: `pnpm -C apps/sdp-docs generate:ai`

## Public vs internal surfaces

Public docs and AI artifacts should mirror the supported public surface only.

- Public API families: `health`, `api-keys`, `wallets`, `projects`, `issuance`, `payments`, `policies`, `compliance`
- Hidden/internal families stay out of public AI resources unless product policy changes: `rpc`, `admin`, `onboarding`, `auth`, `organizations`, `members`

## Preferred checks

- Docs integrity: `pnpm --filter sdp-docs check:links`
- Docs build: `pnpm --filter sdp-docs build`
- Module boundaries: `pnpm check:module-boundaries`
- API playground drift: `pnpm check:api-playground`
- API typecheck: `pnpm --filter @sdp/api typecheck`
- API tests: `pnpm --filter @sdp/api test`
- Full workspace typecheck: `pnpm typecheck`

## Implementation guidance

- Prefer reusing generated docs/OpenAPI metadata instead of duplicating route inventories by hand.
- Keep public URLs coherent with the shared site constants in `@sdp/types/site`.
- When changing docs URLs or discovery resources, update both the docs site and any product links that point at it.
- Update `docs/architecture/module-map.md` with `pnpm generate:module-map`; do not edit it by hand.

## Repo-local skills

- `skills/sdp-tokenization/SKILL.md`: consumer-facing skill for explaining how to tokenize assets with SDP using the supported public docs and API surface.
- `.agents/skills/sdp-ui-designer/SKILL.md`: SDP UI design skill for designing, prototyping, reviewing, or implementing payments, wallets, counterparty, and issuance UI. Its bundle ships the canonical token reference (`sdp-design-system.css`) and the UI handoff rules (`AGENTS.md`) alongside the skill; treat those as the design source of truth for UI work.

When updating repo-local skills:

- keep them grounded in the public docs and API reference instead of internal handlers
- prefer concise `SKILL.md` files with deeper material moved into `references/`
- expose new skills from this file so they remain discoverable through the repo's AI entry point
