# lnkdwn.com — full reference (llms-full.txt)

> Linkdown — turn any Markdown into a shareable link. Operated by 0451
> Software. The short index is at [/llms.txt](https://lnkdwn.com/llms.txt).
> Format spec for this file: https://llmstxt.org.

## 1. Site map

| Path                                  | Auth      | Purpose                                              |
|---------------------------------------|-----------|------------------------------------------------------|
| `/`                                  | none      | Marketing home (served from this dashboard app)      |
| `/cli`                               | none      | CLI install instructions + one-liner                 |
| `/sign-in`                           | none      | Clerk sign-in / sign-up (hosted by Clerk)            |
| `/dashboard`                         | Clerk     | Authenticated dashboard home (deck list)             |
| `/dashboard/billing`                 | Clerk     | Subscription management (links to Stripe portal)     |
| `/d/{token}`                         | none      | Public share viewer (iframe renders the deck)        |
| `/pricing`                           | none      | Pricing tier table + comparison                      |
| `/privacy`                           | none      | Privacy policy (full text)                           |
| `/terms`                             | none      | Terms of service (full text)                         |
| `/docs`                              | none      | Markdown docs index (forthcoming — tracked in plan)  |
| `/install.sh`                        | none      | Bash installer for the Rust CLI                      |
| `/llms.txt`                          | none      | This short index                                     |
| `/llms-full.txt`                     | none      | This file                                            |
| `/openapi.yaml`                      | none      | OpenAPI 3.0.3 spec for the worker API                |
| `/.well-known/security.txt`          | none      | RFC 9116 security disclosure contact                 |
| `/security.txt`                      | none      | Redirects to `/.well-known/security.txt` (RFC 9116) |

The dashboard itself is a Next.js 16 app deployed to Cloudflare Pages
via OpenNext. The worker API runs on Cloudflare Workers (Hono.js, Node
compat). The static content under `/privacy`, `/terms`, `/pricing`,
`/llms.txt`, `/llms-full.txt`, and `/.well-known/security.txt` is
prerendered at build time (`pnpm --filter dashboard build`) and served
as static HTML or text.

## 2. Authentication

### 2.1 Browser (Clerk)

The dashboard uses Clerk for hosted sign-in / sign-up. The dashboard
server components gate on `currentUser()` from `@clerk/nextjs`. The
worker's `/me`, `/decks`, `/shares`, `/billing/portal`, and
`/storage-usage` endpoints accept a Clerk session JWT in
`Authorization: Bearer <token>`. The worker validates the token
against Clerk's Backend API JWKS endpoint (cached). The dashboard
re-signs the bearer on every request from the Clerk session cookie.

### 2.2 CLI (RFC 8628 device flow + RFC 7636 PKCE)

`linkdown login` opens the browser to a Clerk sign-in page tied to
a one-shot user code. Wire flow:

1. `POST /auth/device/code` → `{ device_code, user_code, verification_uri, expires_in, interval, code_challenge, code_challenge_method }`
2. User opens the verification URI, types the user code, signs in.
3. CLI polls `POST /auth/device/token` with the device code + PKCE
   verifier every `interval` seconds. Returns `{ access_token, token_type: "Bearer", expires_in }`.
4. The CLI stores the access token in the OS keyring (macOS
   Keychain / Linux secret-service / Windows Credential Manager) under
   `linkdown-access-token`. The PKCE verifier is stored under
   `linkdown-pkce-verifier` (cleared on logout).
5. The CLI refreshes the token before expiry (no refresh-token
   rotation: the device flow re-issues a fresh access token on
   401 + retry).

`linkdown logout` deletes both keyring entries.

## 3. CLI reference (`linkdown` Rust binary)

Source: `apps/cli/src/main.rs`. README: `apps/cli/README.md`.

### 3.1 Global flags

- `--api-base <URL>` — override the API base (default: `https://api.lnkdwn.com`).
- `--json` — emit machine-readable JSON on stdout (for agents).
- `--no-color` — disable ANSI colour.
- `--verbose` / `-v` — increase log verbosity.

### 3.2 Commands

#### `linkdown login`
Opens browser to the device-flow verification URI and polls for the
access token. Stores credentials in the OS keyring.

#### `linkdown logout`
Removes both keyring entries (`linkdown-access-token` and
`linkdown-pkce-verifier`). Idempotent.

#### `linkdown whoami`
`GET /me` with the stored bearer. Prints: email, Clerk user id,
internal `userId`, `tier`, `storageLimitBytes`, `storageUsedBytes`,
`deckLimit`. With `--json`, emits the raw worker response.

#### `linkdown create [PATH]`
1. Auto-detect the framework at `PATH` (default: `.`).
2. Run the framework's build command:
   - Slidev: `npx slidev build`
   - Marp: `npx @marp-team/marp-cli`
   - Reveal.js: no build step (zip the static output directory).
3. Zip the build output.
4. `POST /decks` → `{ id, uploadUrl, storageKey }`.
5. `PUT <uploadUrl>` with the zip (Content-Type: `application/zip`).
6. `POST /decks/{id}/complete` → finalises; the worker HEADs the R2
   object, checks `sizeBytes` against the tier cap, fires the
   thumbnail worker, and returns the row.
7. `POST /decks/{id}/share` (default link) → prints the share URL.

Flags:
- `--name <NAME>` — explicit deck name (default: directory basename).
- `--framework <slidev|marp|revealjs|remark|custom>` — override auto-detection.
- `--no-share` — skip the default share link creation.
- `--expiry <duration>` (paid tiers only) — `1h`, `24h`, `7d`, `30d`.
- `--password <PW>` (Pro+) — bcrypt-hashed server-side.
- `--view-limit <N>` (Pro+) — integer 1..10000.

#### `linkdown update <name>`
1. `GET /decks` → find the deck by name.
2. `PUT /decks/{id}` with `{ replaceFile: true }` → returns a fresh
   presigned URL pointing at the deck's existing `storageKey`.
3. Re-zip the local build output and PUT it.
4. `POST /decks/{id}/complete` → re-fires the thumbnail worker.
5. Existing share URLs are preserved (the `storageKey` is reused, so
   `/d/{token}` keeps serving the new file).

Flags: same as `create` minus `--name` (taken positionally) and
`--framework` (inferred from the existing deck row).

#### `linkdown list`
`GET /decks?limit=50` (paged via `?cursor=...`). Prints: name,
internal id, status (`processing` / `ready` / `failed`), size,
slide count, created/updated timestamps, share URL (if a default link
exists). With `--json`, emits the full `decks[]` array.

#### `linkdown delete <name>`
`GET /decks` → find by name → `DELETE /decks/{id}`. Cascades to
`shares` (FK cascade) and `storage_usage`. The deck object in R2
is purged by a daily cron (`apps/workers/src/cron.ts`, runs at 03:00
UTC). The CLI does NOT wait for the cron — it returns as soon as the
DB row is gone.

#### `linkdown share <name>`
Creates or rotates a share link. `POST /decks/{id}/share` with the
optional `expiresInDays` / `password` / `viewLimit` body. Prints
the share URL. Free tier: returns 403 `TIER_LIMIT_REACHED` if any
Pro-only field is set. Pro+ tier: the server hashes the password with
bcrypt (cost 12) and stores the hash + the plain-text `viewLimit`.

#### `linkdown unshare <name>`
`DELETE /decks/{id}/share` (bulk revoke). The default share link is
deleted; the underlying deck row is unchanged. Re-running `share`
without `--no-share` regenerates a fresh token.

### 3.3 Framework detection rules

| Framework   | Detection signal                                                          |
|-------------|---------------------------------------------------------------------------|
| Slidev      | `package.json` has `slidev` in `scripts` or `dependencies`           |
| Marp        | `@marp-team/marp-cli` in deps, OR `.marp/` config dir, OR `_mp.md` files |
| Reveal.js   | `index.html` has a `<script src="...reveal.js...">` tag                |

Detection order: `--framework` flag > Marp > Slidev > Reveal.js. If
none match, the CLI exits 1 with a clear error message.

### 3.4 Error codes

| Exit code | Meaning                                                                  |
|-----------|--------------------------------------------------------------------------|
| 1         | Not authenticated — run `linkdown login`                              |
| 2         | Network error (DNS / TCP / TLS)                                          |
| 3         | Build failed (npm install, framework build command, zip)                 |
| 4         | Storage limit exceeded (free tier: 25 MB; Starter: 100 MB; Pro: 1 GB)    |
| 5         | Deck not found                                                           |
| 6         | Tier limit reached (Pro-only flag on a free-tier account)                |
| 7         | Auth refresh failed — run `linkdown login` again                      |
| 64        | CLI usage error (bad flag, missing argument)                             |
| 130       | SIGINT (Ctrl-C)                                                          |

### 3.5 Config

Config at `~/.config/linkdown/config.toml` (XDG-respected). Keys:

- `api_base` (string, default: `https://api.lnkdwn.com`)
- `default_expiry` (string, default: unset)
- `editor` (string, default: `$VISUAL` or `$EDITOR` or `vi`)

The keyring is the source of truth for the access token; the config
file is for non-secret settings only.

## 4. API reference (worker)

The full OpenAPI spec is at `/openapi.yaml` (also checked in at
`apps/workers/src/openapi.yaml`). The list below is the route table
the worker actually serves, with auth, rate limit, and a one-line
summary. For request/response schemas and error envelopes, follow the
link in each row.

Base URL: `https://api.lnkdwn.com` (prod) / `https://api.staging.lnkdwn.com` (staging).

### 4.1 Health

| Method | Path       | Auth | Rate limit | Summary                                 |
|--------|------------|------|------------|-----------------------------------------|
| GET    | `/health`| none | none       | Liveness probe. Returns ISO timestamp.  |

### 4.2 Auth (RFC 8628 device flow)

| Method | Path                    | Auth | Rate limit      | Summary                                                |
|--------|-------------------------|------|-----------------|--------------------------------------------------------|
| POST   | `/auth/device/code`    | none | 10/min/IP       | Request a device + user code (returns PKCE challenge). |
| POST   | `/auth/device/token`   | none | 60/min/IP       | Poll for the access token.                             |

### 4.3 Authenticated — user

| Method | Path                | Auth   | Rate limit    | Summary                                                |
|--------|---------------------|--------|---------------|--------------------------------------------------------|
| GET    | `/me`              | Bearer | 120/min/uid   | Profile + tier + storage + deck-limit snapshot.        |
| GET    | `/storage-usage`   | Bearer | 120/min/uid   | `{ usedBytes, limitBytes, tier }`.                    |

### 4.4 Authenticated — decks

| Method | Path                          | Auth   | Rate limit    | Summary                                                |
|--------|-------------------------------|--------|---------------|--------------------------------------------------------|
| POST   | `/decks`                    | Bearer | 50/min/uid    | Create a deck row in `processing`, get upload URL.   |
| GET    | `/decks`                    | Bearer | 120/min/uid   | List the caller's decks (paged via `?cursor=`).       |
| GET    | `/decks/{id}`               | Bearer | 120/min/uid   | Single deck row.                                       |
| PUT    | `/decks/{id}`               | Bearer | 50/min/uid    | Update metadata; or `replaceFile: true` to refresh.  |
| DELETE | `/decks/{id}`               | Bearer | 60/min/uid    | Delete the deck (cascades shares + storage).           |
| POST   | `/decks/{id}/complete`      | Bearer | 50/min/uid    | Finalise upload; worker HEADs R2, enforces tier caps.  |
| POST   | `/decks/{id}/share`         | Bearer | 60/min/uid    | Create or rotate the default share link.               |
| GET    | `/decks/{id}/share`         | Bearer | 60/min/uid    | List the deck's share links (preserves default token). |
| DELETE | `/decks/{id}/share`         | Bearer | 60/min/uid    | Revoke all share links for the deck (bulk).            |

### 4.5 Authenticated — share management

| Method | Path             | Auth   | Rate limit    | Summary                                              |
|--------|------------------|--------|---------------|------------------------------------------------------|
| GET    | `/shares`       | Bearer | 60/min/uid    | List all share links owned by the caller.            |
| DELETE | `/shares/{id}`  | Bearer | 60/min/uid    | Revoke a single share link.                          |

### 4.6 Public — share viewer

| Method | Path                      | Auth | Rate limit   | Summary                                                  |
|--------|---------------------------|------|--------------|----------------------------------------------------------|
| GET    | `/d/{token}`             | none | 120/min/IP   | Returns the HTML viewer (renders the deck in iframe).    |
| GET    | `/d/{token}/file`        | none | 120/min/IP   | Returns the raw deck zip (for iframe `srcdoc` loading). |
| GET    | `/d/{token}/info`        | none | 120/min/IP   | Returns `{ title, sizeBytes, expiresAt, viewCount, slideCount }` (no PII). |

### 4.7 Billing

| Method | Path                 | Auth   | Rate limit    | Summary                                              |
|--------|----------------------|--------|---------------|------------------------------------------------------|
| POST   | `/billing/portal`   | Bearer | 60/min/uid    | Creates a Stripe billing portal session; returns URL. |

### 4.8 Webhooks (HMAC-signed)

| Method | Path                  | Auth         | Summary                                                    |
|--------|-----------------------|--------------|------------------------------------------------------------|
| POST   | `/webhooks/clerk`    | Svix HMAC    | User lifecycle events (`user.created`, `user.updated`, `user.deleted`). The `user.deleted` event purges the R2 prefix. |
| POST   | `/webhooks/stripe`  | Stripe HMAC  | Subscription + invoice events. Drives `users.tier` / `periodEnd` / `delinquent`. |

### 4.9 Error envelopes

Two coexisting envelopes (see OpenAPI `components.schemas` for full
shape):

1. **Legacy**: `{ error: string, code?: string }` — pre-existing
   endpoints in `routes/auth.ts`, `routes/decks.ts`,
   `routes/share.ts`. `code` is present on most 4xx paths, omitted
   on 500. The 404 handler returns `{ error: "Not found", code: "NOT_FOUND" }`.
2. **Standard**: `{ code: ErrorCode, message: string, details?: object }` —
   the `app.onError` hook and `errorResponse` helper. `code` is
   one of the `ErrorCode` enum values; `message` is human-readable;
   `details` carries field-level validation errors keyed by field
   name.

### 4.10 Rate limits

Per-binding limits (declared in `apps/workers/wrangler.jsonc` and
surfaced in OpenAPI):

| Binding              | Limit       | Used by                                                  |
|----------------------|-------------|----------------------------------------------------------|
| `RL_DEVICE_CODE`    | 10/min/IP   | `POST /auth/device/code`                                |
| `RL_DEVICE_TOKEN`   | 60/min/IP   | `POST /auth/device/token`                               |
| `RL_DECKS_CREATE`   | 50/min/uid  | `POST /decks`                                           |
| `RL_SHARE_VIEW`     | 120/min/IP  | `GET /d/{token}`, `GET /d/{token}/file`                |
| `RL_SHARE_INFO`     | 120/min/IP  | `GET /d/{token}/info`                                   |
| `RL_SHARE_LIST`     | 60/min/uid  | `GET /shares`, `GET /decks/{id}/share`                 |
| `RL_SHARE_DELETE`   | 60/min/uid  | `DELETE /shares/{id}`                                   |
| `RL_BILLING_PORTAL` | 60/min/uid  | `POST /billing/portal`                                  |

On exceed: `429 { error: "Rate limit exceeded", code: "RATE_LIMITED" }`
with a `Retry-After: 60` header.

## 5. Pricing tiers (full table)

Source of truth: `docs/plans/marketing/business-model.md:139-156` (the
"3.1 Tier matrix" table). Pinned by
`apps/workers/tests/storage-limits.test.mjs` (launch A.7#36) so the
marketing copy cannot drift away from the code.

| Feature                       | **Free**       | **Starter** $5/mo    | **Pro** $15/mo      | **Team** $49/mo       |
|-------------------------------|----------------|----------------------|---------------------|------------------------|
| **Storage**                   | 25 MB          | 100 MB               | 1 GB                | 10 GB                  |
| **Max deck size**             | 500 KB         | 5 MB                 | 25 MB               | 100 MB                 |
| **Decks count**               | 3              | 50                   | 50                  | Unlimited              |
| **Slides per deck**           | 15             | 50                   | 50                  | Unlimited              |
| **Image assets**              | ❌             | ✅                   | ✅                  | ✅                     |
| **Custom slug**               | ❌             | ✅                   | ✅                  | ✅                     |
| **Expiring links** (1h → 30d) | ❌             | ✅ (up to 7d)        | ✅                  | ✅                     |
| **Password-protected links**  | ❌             | ❌                   | ✅                  | ✅                     |
| **View-limit links**          | ❌             | ❌                   | ✅                  | ✅                     |
| **Link analytics**            | ❌             | Basic (counts)       | Full (geo, ref, time) | Full + export        |
| **API access**                | ❌             | ❌                   | ✅                  | ✅                     |
| **Webhooks**                  | ❌             | ❌                   | ❌                  | ✅                     |
| **Org / team seats**          | 1              | 1                    | 1                   | 5 (then $9/seat)       |
| **Custom domain**             | ❌             | ❌                   | ❌                  | $5/mo add-on           |
| **SSO (Google / GitHub)**     | ❌             | ❌                   | ❌                  | ✅ (free in tier)      |
| **Branded share page**        | ❌             | ❌                   | ❌                  | ✅                     |
| **SLA / support**             | Community      | Community            | Email <48h          | Email <8h + Slack      |

### 5.1 Annual plans

- Starter: $50/yr (2 months free).
- Pro: $150/yr.
- Team: $490/yr.

### 5.2 Add-ons (Team tier and above)

- **Custom domain:** $5/mo per domain (1 free in Team tier).
- **SSO (SAML / OIDC):** $99/mo per organization.
- **SLA-backed support:** $249/mo per organization.

### 5.3 Upgrade trigger choreography

The CLI and dashboard both surface a "you're at N% of your limit"
nudge at 80% storage and 2/3 of the deck count:

| Trigger            | Free          | Starter   | Pro       | Team |
|--------------------|---------------|-----------|-----------|------|
| 2/3 decks          | Soft banner   | —         | —         | —    |
| 3/3 decks          | Hard block + upgrade CTA | — | — | — |
| 4/25 decks         | —             | Soft banner | —       | —    |
| 25/25 decks        | —             | Hard block | —       | —    |
| Storage ≥ 80%      | —             | Soft banner | Soft banner | — |

The worker's `GET /me` returns `{ tier, storageLimitBytes,
storageUsedBytes, deckLimit }` so the CLI can render the same state
without a second round-trip.

### 5.4 Free-tier specifics (pinned by tests)

- Storage cap: 25 MB (25 MiB = 26,214,400 bytes binary; see
  `apps/workers/src/lib/auth.ts:124-128`). Pinned by
  `apps/workers/tests/storage-limits.test.mjs`.
- Deck count: 3 (was 5 pre-launch; see
  `docs/decisions/0001-free-tier-limits.md`).
- Per-deck size: 0.5 MB (524,288 bytes; was 2 MB pre-launch).
- Slide count: 15 per deck (was 20 pre-launch).
- No image assets, no custom slug, no expiring / password / view-limit
  shares.
- Server-side enforcement uses `head().size` from R2, NOT the
  client-supplied `sizeBytes` — the storage quota is real bytes on
  disk.

## 6. Privacy summary (full text at /privacy)

### 6.1 Data we collect

- **Account data** (email, name, avatar) — via Clerk. We never see the password.
- **Billing data** (Stripe customer id, subscription tier, billing
  period end, payment status) — via Stripe webhooks. We never see
  the card number.
- **Uploaded decks** — in Cloudflare R2, default US region.
- **Share-link metadata** — in Postgres on Neon, US region.
- **Operational logs** — 30 days, Cloudflare Workers tail / Logpush.
  PII-scrubbed: raw email and raw Stripe customer id are NOT logged;
  emails are replaced with a 12-char sha256 hash.
- **Error reports** — 90 days, Sentry. PII-scrubbed per
  `sendDefaultPii: false`.

### 6.2 Data we explicitly do NOT collect

- No advertising trackers.
- No third-party analytics on the dashboard.
- No browser fingerprinting.
- No data sale.

### 6.3 Cookies

A single first-party Clerk session cookie (`__session`,
`HttpOnly` + `Secure` + `SameSite=Lax`). Plausible (used only on
the marketing site, NOT on the dashboard) is cookieless.

### 6.4 Retention

- Decks and shares: until the user deletes them.
- Account data: deleted within 60 seconds of the Clerk `user.deleted`
  webhook (cascades `users` → `decks` → `shares` → `storage_usage`
  via FK cascade; R2 prefix purged in the same handler).
- Operational logs: 30 days.
- Error reports: 90 days.
- Billing data: 7 years (US tax law).

### 6.5 GDPR / CCPA rights

EU/UK users have the right to: access, correct, delete, export,
object, withdraw consent, lodge a complaint with a supervisory
authority. Exercised by emailing `privacy@0451software.com`. We
respond within 30 days.

### 6.6 Children

Minimum age: 16. We do not knowingly collect data from anyone under
16. If you believe we have, email `privacy@0451software.com` and we
will delete the account within 7 days.

### 6.7 Changes to this policy

14-day notice for material changes, with a dashboard banner
announcing the change. The previous version is preserved at
`/privacy?from=YYYY-MM-DD` for 60 days after a change takes effect.

### 6.8 Contact

- Privacy / data subject requests: `privacy@0451software.com`
- Security disclosure: `security@0451software.com` (PGP key at
  `/.well-known/security.txt`)
- Abuse: `abuse@0451software.com`

## 7. Terms of service (summary; full text at /terms)

14 sections. Key points:

- **Acceptance:** by using the service, you agree to these terms.
- **Your content:** you retain all rights. You grant us a limited
  license to operate the service (host, transmit, cache, generate
  thumbnails). Content prohibitions: illegal content, IP-infringing
  material, malware, harassment, doxxing, NCII.
- **Plans and payment:** Stripe handles payments. Monthly, cancel
  anytime, no prorate refunds. 3-day grace period on failed payment
  before downgrade to free. EU consumers retain the 14-day
  right-of-withdrawal per consumer law.
- **Acceptable use:** no abuse, no scraping for training datasets
  without our written consent, no automated account creation.
- **Termination:** we may suspend for ToS violations; you may delete
  your account at any time via `linkdown logout` + Clerk account
  deletion (triggers the `user.deleted` webhook → full purge within
  60 seconds).
- **Limitation of liability:** capped at the greater of $100 USD or
  the fees paid in the preceding 12 months.
- **Governing law:** Delaware, with an EU consumer carve-out (your
  local mandatory consumer law applies if you are an EU consumer).
- **Changes:** 14-day notice for material changes.

## 8. Pointers for LLM agents

- **Schema:** GET `/openapi.yaml` for the worker API. The dashboard
  pages are not API-driven (they are server components); the worker
  is.
- **Health:** GET `https://api.lnkdwn.com/health` → `{ "status": "ok", "timestamp": "<iso>" }`.
- **Public deck info (no auth):** GET `https://lnkdwn.com/d/{token}/info`
  → `{ title, sizeBytes, expiresAt, viewCount, slideCount }`. Useful
  for verifying a share link is still live without rendering the
  viewer.
- **Install the CLI:** `curl -fsSL https://lnkdwn.com/install.sh | sh`
  then `linkdown login`.
- **Cite this file:** the canonical URL is `https://lnkdwn.com/llms-full.txt`.
  Format reference: https://llmstxt.org.

## 9. Source and license

- Source: https://github.com/0451-software/linkdown
- License: UNLICENSED (proprietary). Source available on request.
- Operator: 0451 Software.