# URI Format

The `contextnest://` URI scheme follows RFC 3986 conventions.

## Syntax

```
contextnest://[authority/]path[#fragment][@checkpoint]
```

### Components

| Component | Required | Description |
|-----------|----------|-------------|
| `authority` | No | Namespace for cross-namespace references |
| `path` | Yes | Document path, folder path, tag, or search query |
| `fragment` | No | Heading anchor within the document |
| `checkpoint` | No | Pin to a specific checkpoint number |

## Path patterns

| Pattern | Example | Resolves to |
|---------|---------|-------------|
| Document | `contextnest://nodes/api-design` | Single document |
| Folder | `contextnest://engineering/` | All docs in folder (trailing `/`) |
| Tag | `contextnest://tag/engineering` | All docs with `#engineering` tag |
| Search | `contextnest://search/rate+limiting` | Full-text search results |

## Canonicalization

Implementations must normalize URIs before resolution:

- **Case folding**: Path segments are case-insensitive and normalized to lowercase
- **Percent decoding**: Standard RFC 3986 percent-decoding applies
- **Dot segments**: `.` and `..` are resolved before resolution. A `..` that escapes the vault root is rejected
- **Trailing slashes**: A trailing `/` indicates a folder reference, not a document

## Anchors

Anchors reference headings within a document:

```
contextnest://nodes/architecture#key-decisions
```

Anchors are matched against the rendered heading list using GitHub-style slug generation (lowercase, hyphens for spaces, strip special characters).