Add authoring guidance files

.cursor/rules/asides.mdc

@@ -0,0 +1,25 @@
+---
+description: Tips authoring guidance. Use Mintlify callouts. Short, optional, not workflows.
+alwaysApply: true
+---
+Mintlify only. Render tips with <Tip>, <Note>, or <Warning> callouts.
+Keep each callout 1–3 sentences. Optional, not required to complete the task.
+Place tips after the core steps or next to the relevant step.
+Use <Tip> for shortcuts, <Note> for caveats or context, <Warning> for risks or data loss.
+Do not chain steps inside tips; move any multi-step guidance to the main text or a tutorial.
+Avoid duplication with FAQs; link if the answer is longer.
+Use standard punctuation. No marketing language.
+
+Example:
+```md
+<Tip>
+Save a view before sharing so recipients land on the right perspective.
+</Tip>
+
+<Info>
+Large models may take longer to index in the viewer. You can navigate sooner, but filters may appear gradually.
+</Info>
+
+<Warning>
+Publishing to a private project will restrict access for outside collaborators. Check permissions before sharing the link.
+</Warning>

.cursor/rules/base.mdc

@@ -0,0 +1,12 @@
+---
+description: Global authoring guidance for Speckle docs. Mintlify components, approachable tone, task-first structure, visuals, FAQs/best practices/tips, no tutorials in core docs.
+alwaysApply: true
+---
+Mintlify only. Prefer Mint components over raw HTML or Markdown.
+Approachable, precise tone. No jargon. Short, imperative sentences.
+Task-first. Show the outcome of each step. Keep pages brief.
+Use visuals where they clarify; add captions or callouts if needed.
+Add a compact FAQ, best practices, and 1–3 tips when appropriate.
+Keep tutorials separate; link out if a workflow needs more than 3–5 steps.
+Cross-link related pages. Name sections by user intent.
+Avoid filler words and marketing language. Prefer standard punctuation.

.cursor/rules/faqs.mdc

@@ -0,0 +1,22 @@
+---
+description: FAQ authoring guidance. Use Mintlify Accordions. Keep answers short, user-language, and actionable. Avoid tutorials.
+alwaysApply: true
+---
+Mintlify only. Render FAQs with `<AccordionGroup>` and `<Accordion title="…">` items.
+Keep each Q/A atomic: 1–3 sentences or one annotated screenshot.
+Use user language for questions. Avoid jargon.
+If the answer needs more than a few lines, link to the relevant doc instead.
+Include at least one edge-case question where applicable.
+Avoid filler and marketing language. Use standard punctuation.
+
+
+Example:
+```md
+<AccordionGroup>
+<Accordion title="Can I share with someone without a Speckle account?">
+Yes. They will receive an email invite and can open the model in their browser. You can change their permissions from **Share**.
+</Accordion>
+<Accordion title="Where does my model appear after I publish from Revit?">
+In the web app, open your project and find the model under **Models**. The latest version is at the top. See **Viewing & Sharing** for navigation tips.
+</Accordion>
+</AccordionGroup>

.cursor/rules/steps.mdc

@@ -0,0 +1,54 @@
+---
+description: Step-by-step authoring guidance. Use Mintlify <Steps>/<Step>. Imperative, outcome-oriented, brief. Include sign-in for connector flows.
+alwaysApply: false
+---
+Mintlify only. Wrap sequences in `<Steps>` with individual `<Step title="…">` items.
+
+Titles
+- Start with a verb. Sentence case. 3-7 words.
+
+Content
+- 1-3 short sentences per step. Keep it scannable.
+- If you need substeps, use a short ordered list. Avoid deep nesting.
+- End with the outcome: what the user should see or be able to do.
+- Use one callout max per step: `<Tip>`, `<Note>`, or `<Warning>`.
+- Include visuals only when they clarify. Prefer Mintlify `<Image>` with alt text.
+
+Links and scope
+- Cross-link related docs where it helps.
+- If a flow needs more than 3-5 steps or long substeps, or offering an opinion for best options to use, link to a tutorial instead of expanding here.
+
+Connector-specific
+- Include an "Open your host app and sign in" step before publish/load.
+- After Publish/Load, point to the exact place in the web app where the data appears.
+
+Example
+```md
+<Steps>
+  <Step title="Create a Speckle account">
+    Go to [app.speckle.systems](https://app.speckle.systems) and create an account.
+  </Step>
+
+  <Step title="Get the connector">
+    Download the installer from the [Connectors directory](https://speckle.systems/connectors).
+  </Step>
+
+  <Step title="Install the connector">
+    <Warning>Close the host application before installing.</Warning>
+    1. Run the installer.
+    2. Follow the prompts to complete installation.
+  </Step>
+
+  <Step title="Open your host app and sign in">
+    Launch your host app, open the Speckle panel, and select **Sign in**. Complete sign in in your browser.
+  </Step>
+
+  <Step title="Publish your first model">
+    Select a small test selection and choose **Publish**. You should see a success message with a link to the model.
+    <Tip>Start with a small selection to validate the pipeline.</Tip>
+  </Step>
+
+  <Step title="View it in the browser">
+    Open the link. In the web app, the model appears under **Models** in your project.
+  </Step>
+</Steps>

.devcontainer/devcontainer.json

@@ -25,7 +25,8 @@
         "mintlify.mintlify-vscode",
         "mintlify.mintlify-snippets",
         "mintlify.document",
-        "unifiedjs.vscode-mdx"
+        "unifiedjs.vscode-mdx",
+        "nuxt.mdc"
       ]
     }
   },

AUTHORING.md

@@ -0,0 +1,117 @@
+# AUTHORING.md — AI Authoring Guidance (Not the Contributor README)
+
+This file is **for training/priming AI assistants** (Cursor, ChatGPT, Claude, Copilot) to write and review Speckle docs consistently. It is **not** the contributor README. For human setup instructions (Mintlify, devcontainer, publishing), see **README.md**.
+
+The **canonical, path‑scoped rules** live in `.cursor/rules/*.mdc`. This file summarizes those rules in one place so non‑Cursor tools can follow them.
+
+---
+
+## Our approach to users
+
+* **User‑first, purpose‑first**: frame topics by the action (publish, load, share, view), not the plumbing (connectors, integrations).
+* **Day‑0 success**: shortest path to a visible win; minimal decisions; show outcomes.
+* **Brevity with depth**: core pages stay concise; depth lives in **FAQs**, **Best practices**, and **Tips**.
+* **Visual clarity**: use screenshots/short clips when they reduce cognitive load; add captions when the image carries meaning.
+* **Plain language**: approachable, precise, no jargon; imperative steps.
+* **Honest guardrails**: call out limitations, known issues, version differences.
+* **Connectors are a subset**: everyone uses the web app; not everyone uses connectors.
+
+---
+
+## Global authoring rules (summary of `base.mdc`)
+
+* **Mintlify only**: prefer Mint components over raw HTML/Markdown.
+* **Tone**: approachable, precise; short, imperative sentences.
+* **Structure**: task‑first; show outcomes; keep pages brief.
+* **Visuals**: include only when they clarify; add captions/callouts if needed.
+* **Extras**: add a compact **FAQ**, **Best practices**, and **1–3 Tips** where appropriate.
+* **Tutorials**: keep tutorials separate; if a flow needs >3–5 steps, link out.
+* **Cross‑link & naming**: cross‑link related pages; name sections by user intent.
+
+---
+
+## Steps (summary of `steps.mdc`)
+
+* Use **`<Steps>`/`<Step>`** for short, linear sequences.
+* **Titles**: verb‑first, sentence case, \~3–7 words.
+* **Content**: 1–3 short sentences or a short ordered list; end with the **outcome**.
+* **Do not nest complex components** (Tabs, Accordions, code blocks) inside `<Step>`.
+* Put `<Tip>`, `<Note>`, `<Warning>` **adjacent** to the Steps block (not inside).
+* **Fallback** when Steps need rich content: use `###` + ordered list instead of `<Steps>`.
+
+---
+
+## FAQs (summary of `faq.mdc`)
+
+* Render with **`<AccordionGroup>` + `<Accordion title="…">`** items.
+* Q/A pairs are atomic (1–3 sentences or one annotated screenshot) using user language.
+* If longer, **link out** to the relevant doc.
+* Include at least one edge case.
+
+---
+
+## Tips & asides (summary of `tips.mdc`)
+
+* Use **`<Tip>`**, **`<Note>`**, **`<Warning>`**.
+* 1–3 sentences; optional, not a workflow.
+* Place near the relevant step or after the core steps.
+
+---
+
+## Publishing & Loading (connectors) (summary of `connectors.mdc`)
+
+* **Purpose‑first**: write about **publish** and **load**, not connector names.
+* **Use this H2 order**:
+
+  1. Install
+  2. Open & sign in
+  3. Publish
+  4. Load
+  5. Common tasks (3–5 micro‑guides)
+  6. FAQ (Accordion)
+  7. Troubleshooting (top issues, log path, forum link)
+  8. Known issues
+* **Header panel**: supported host versions, connector version, last updated, download, changelog.
+* **Web app handoff**: after Publish/Load, show exactly where the data appears in the browser and link to Viewing & Sharing / Workspace.
+
+---
+
+## How to use this file with different tools
+
+### Cursor
+
+Cursor auto‑attaches rules from `.cursor/rules/*.mdc`. Keep those files authoritative. This `AUTHORING.md` is just a human/agent summary.
+
+### ChatGPT
+
+* Paste the **Prompt Seed** (below) into Custom Instructions or your first message; pin it in the thread.
+* When asking for edits, reference the relevant rules (e.g., “follow `connectors.mdc` H2 order”).
+
+### Claude
+
+* Create a **sub‑agent** or attach this file as context; reference the rules sections explicitly.
+
+### Copilot (Chat)
+
+* Open `AUTHORING.md` and say: “Use this document as guidance for all doc edits in this session.”
+* Add a short banner comment at the top of the page you’re editing to nudge inline completions:
+  `<!-- style: mintlify components; FAQs=AccordionGroup; steps=no nested components -->`
+
+---
+
+## Prompt Seed (paste into your AI tool once per session)
+
+> You are writing docs for Speckle. Follow **AUTHORING.md** in the repo and the canonical rules in `.cursor/rules/*.mdc`.
+>
+> **Global**: Mintlify components only; approachable, precise tone; short, imperative sentences; task‑first; show outcomes; keep pages brief; visuals when they clarify; compact FAQ + best practices + 1–3 Tips; no tutorials in core docs; cross‑link by user intent.
+>
+> **Steps**: use `<Steps>`/`<Step>` for short sequences; verb‑first titles; do **not** nest complex components; render callouts adjacent; fallback to `###` + ordered list if needed.
+>
+> **FAQs**: use `<AccordionGroup>` + `<Accordion title="…">`; answers are atomic; link out if longer; include an edge case.
+>
+> **Connectors**: frame by purpose (publish/load), not connector names; H2 order = Install → Open & sign in → Publish → Load → Common tasks → FAQ → Troubleshooting → Known issues; add a header panel (versions, download, changelog); always show the web‑app handoff.
+
+---
+
+**Source of truth:** `.cursor/rules/*.mdc`
+**Contributor setup:** see `README.md`.

speckle-docs-NEW.code-workspace

@@ -1,6 +1,5 @@
 {
   "folders": [
-    { "name": "Live Site", "uri": "https://speckle.systems" },
     { "path": "./developers/automate/", "name": "Automate" },
     { "path": "./developers/server/", "name": "Server" },
     { "path": "./developers/viewer/", "name": "Viewer" },