---
title: Resource Documentation
description: How docs ship alongside code in the Elevasis SDK -- directory structure, frontmatter schema, size limits, deploy behavior, and the /docs command
loadWhen: "Working with resource documentation or the /docs command"
---

`elevasis-sdk deploy` ships your code and your documentation atomically -- one command, no version drift. Documentation files live in a `docs/` directory at your project root and render in the Elevasis platform UI for operators using your resources.

## Directory Structure

Create `.mdx` files inside a `docs/` directory at your project root. Your Elevasis SDK project includes a starter structure:

```
my-project/
├── docs/
│   └── index.mdx          # Resource overview (included by default)
├── src/
│   └── index.ts            # Resource definitions
└── elevasis.config.ts
```

A missing `docs/` directory is silently ignored -- documentation is optional. If the directory exists, its contents are included in the deploy payload alongside resource schemas.

## Frontmatter Schema

```yaml
---
title: string       # Page title (required)
description: string # Short description (optional)
order: number       # Sort order within directory (optional, default: 0)
---
```

## Naming Conventions

- `docs/index.md` is the root page and is always rendered first
- Nested directories create sections: `docs/guides/getting-started.mdx`
- File names become URL slugs: `setup-guide.mdx` renders at `/docs/setup-guide`
- Arbitrary nesting is supported -- no depth limit

## Size Limits

- 100KB per file
- 1MB total across all files in a deployment

These limits are enforced by the CLI before the deploy request is sent. Validation errors include the file name and size.

## Deploy Behavior

When you run `elevasis-sdk deploy`:

1. The CLI scans `docs/` recursively for `.mdx` files
2. Each file's frontmatter (title, description, order) is parsed and stripped from the content
3. Total size is validated against the 1MB limit and individual files against 100KB
4. The documentation array is included in the deploy metadata alongside your resource schemas

Documentation and code ship in the same transaction. There is no separate upload step and no way for documentation to drift out of sync with the deployed version.

## The /docs Command

The `/docs` command manages the permanent `docs/` tree in your project. It operates on everything in `docs/` except `docs/in-progress/` (owned by `/work`) and auto-generated files (`project-map.mdx`, `resource-map.mdx`).

**Browse (default):** Running `/docs` with no arguments scans `docs/` recursively and presents a numbered list of user-maintained docs. Pick a number to read and discuss the doc, or say "create" or "verify."

**Create:** `/docs create [description]` runs an interview-driven flow. It asks what you want to document, determines placement, scans `src/` to pre-populate from code, and creates the file with appropriate sections.

Section templates by doc type:

- **Resource guide:** Overview, Input/Output, How It Works, Platform Tools Used, Configuration
- **Integration guide:** Overview, Setup (credentials), Data Model, Usage Patterns, Troubleshooting
- **Architecture notes:** Context, Decision, Consequences, Alternatives Considered
- **Process doc:** Purpose, Prerequisites, Steps, Recovery

**Verify:** `/docs verify [file?]` checks docs against current code interactively. Without an argument, it scans all user-maintained docs, cross-references resource IDs, schema fields, and platform tools against `src/`, and offers to fix or create docs for undocumented resources.

## Command Routing Reference

| Scenario                                | Command                                               |
| --------------------------------------- | ----------------------------------------------------- |
| Starting new work                       | `/work` (auto-detects new work from your description) |
| Resuming yesterday's work               | `/work` (auto-resumes if one task is in-progress)     |
| Browsing what docs exist                | `/docs`                                               |
| Creating a reference doc (not a task)   | `/docs create`                                        |
| Checking if docs match current code     | `/docs verify`                                        |
| Full maintenance pipeline (8 steps)     | `/meta fix`                                           |
| Deploying code and auto-generating maps | `/meta deploy`                                        |

---

**Last Updated:** 2026-03-06
