proj-docs-revamp

.gitignore

@@ -8,4 +8,5 @@ build
 
 # windsurf rules
 .windsurfrules
-CLAUDE.md
+CLAUDE.md
+.claude/

.nvmrc

@@ -1 +1 @@
-18.18.2
+20.20.2

DESIGN-WORKFLOW.md

@@ -0,0 +1,84 @@
+# Docs design workflow
+
+Guide for contributing design changes to the Turnkey Mintlify docs (welcome page revamp and related UI).
+
+## Branch strategy
+
+- Base design work on **`graham/docs-revamp`** (or a short-lived branch from it, e.g. `serge/design-welcome`).
+- Open PRs **into `graham/docs-revamp`** until the revamp merges to `main`.
+- Sync often to avoid drift from the Mintlify preview:
+
+```sh
+git fetch origin
+git merge origin/graham/docs-revamp
+```
+
+Production deploys from **`main`** (see README).
+
+## Files to edit
+
+| Change | Files |
+|--------|--------|
+| Welcome / landing layout | `welcome.mdx` |
+| Welcome / shared UI styles | `styles.css` (`.tk-*` classes) |
+| Site-wide color, nav, fonts | `docs.json` |
+| Illustrations, icons | `images/` (use `/images/...` paths) |
+| Logos / favicon | `logo/`, `favicon.svg` |
+
+Avoid unless intentional:
+
+- `generated-docs/`, `api-reference/` (generated — use `make gen` for API reference)
+- Duplicating content in `snippets/shared/` (update the snippet once; see README)
+
+## Local development
+
+Mintlify CLI requires **Node ≥ 20.17** (`.nvmrc` may list an older version).
+
+```sh
+nvm use 20
+cd docs   # directory containing docs.json
+mintlify dev
+```
+
+Preview welcome: http://localhost:3000/welcome
+
+Before opening a PR:
+
+```sh
+mintlify validate
+```
+
+### Common pitfall
+
+Use **straight ASCII quotes** (`'`) in imports and JSX — not curly/smart quotes (`‘` `’`). Smart quotes in `import` paths or `style={{}}` cause MDX parse errors and can blank pages during `mintlify dev`.
+
+## Shipping to the team
+
+1. Make focused commits (e.g. hero spacing, nav labels — not one giant “design” commit).
+2. Push your branch to `tkhq/docs`.
+3. Open a PR **into `graham/docs-revamp`** with:
+   - What changed (welcome vs sitewide)
+   - Before/after screenshots (light and dark if relevant)
+   - Mintlify preview link from the PR checks
+   - Local test steps: `mintlify dev` → `/welcome`
+4. Request review from the revamp owner / docs maintainers.
+5. Merge via team process; do not merge to `main` unless agreed.
+
+## Style conventions
+
+- Prefer **CSS classes in `styles.css`** over large inline `style={{}}` in `welcome.mdx`.
+- Commit image assets in-repo; do not rely only on Mintlify CDN URLs for new art.
+- `welcome.mdx` uses `mode: "custom"` for a full-width landing layout (navbar only).
+
+## Access
+
+- **GitHub:** write access to `tkhq/docs` allows push + PR without a fork.
+- **Mintlify dashboard:** optional (`mintlify login`); not required for local preview.
+
+## Quick checklist
+
+- [ ] Branch is up to date with `origin/graham/docs-revamp`
+- [ ] `mintlify dev` — `/welcome` looks correct (light + dark)
+- [ ] `mintlify validate` passes
+- [ ] No smart quotes in imports / JSX
+- [ ] PR targets `graham/docs-revamp` with screenshots

api-reference/activities/overview.mdx

@@ -1,24 +1,21 @@
 ---
 title: "Activities"
-description: "Activities are requests to securely execute a workload in Turnkey."
+description: "Activities are requests to securely execute a workload in Turnkey. Submission endpoints are always prefixed with `/public/v1/submit`."
 sidebarTitle: "Overview"
 mode: wide
 ---
 
 # What are activities?
 
-Activities (also called [submissions](/developer-reference/api-overview/submissions)) are requests to create, modify, or use resources within Turnkey.
+Activities are requests to create, modify, or use resources within Turnkey.
 Submission endpoints are always prefixed with `/public/v1/submit`.
 
-- **Policy Enforcement:** Activities are subject to consensus or condition enforcement via the policy engine.
-- **Optimistic Execution:** Activities are executed optimistically synchronous—if possible, the request completes synchronously; otherwise, it falls back to asynchronous processing.
-- **Activity Status:**
-  - `COMPLETED`: The activity was successful and the `result` field is populated.
-  - `FAILED`: The activity failed and the `failure` field contains the reason.
-  - `CONSENSUS_NEEDED`: More signatures are required to process the request.
-  - `PENDING`: The request is processing asynchronously.
-- **Approval expiration:** Activities do not expire. However, approvals expire 24 hours after the first vote if consensus is not reached, and must be re-submitted while the activity remains in ACTIVITY_STATUS_CONSENSUS_NEEDED.
-- **Status Updates:** You can get updates by re-submitting the request (idempotent) or polling `get_activity` with the activity ID.
-- **Idempotency:** The API is idempotent—identical requests (same POST body) return the same activity. To generate a new activity, change the `timestampMs` value in your request.
-
-
+- **Policy enforcement:** Activities are subject to consensus or condition enforcement via the policy engine.
+- **Optimistic execution:** Activities execute optimistically synchronous — if possible, the request completes synchronously; otherwise it falls back to asynchronous processing. Your services should account for this by checking the activity status in the response:
+  - `ACTIVITY_STATUS_COMPLETED`: The activity succeeded and the `result` field is populated.
+  - `ACTIVITY_STATUS_FAILED`: The activity failed and the `failure` field contains the reason.
+  - `ACTIVITY_STATUS_CONSENSUS_NEEDED`: More signatures (votes) are required to process the request.
+  - `ACTIVITY_STATUS_PENDING`: The request is processing asynchronously.
+- **Approval expiration:** Activities do not expire. However, when an activity is submitted, the requester's submission counts as the first approval and starts a 24-hour window. If consensus is not reached within that window, existing approvals expire and must be re-submitted while the activity remains in `ACTIVITY_STATUS_CONSENSUS_NEEDED`.
+- **Status updates:** Poll `get_activity` with the `activity.id`, or re-submit the original request (see idempotency below).
+- **Idempotency:** The submission API is idempotent. Each request's POST body is hashed into a fingerprint — any two requests with the same fingerprint return the same activity. To generate a new activity, change the `timestampMs` value in your request.