feat: unified docs space, wizard with remote repo form, image fixes (#23)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: automation-nsheaps[bot] <251779498+automation-nsheaps[bot]@users.noreply.github.com>

Author: 3 people

.claude/rules/content-formatting.md

@@ -0,0 +1,47 @@
+# Content Formatting
+
+All user-facing content (documentation, page content, inline help) follows these formatting rules.
+
+## Markdown Syntax
+
+- Use **standard Markdown** as the primary content format
+- Fall back to **GitHub Flavored Markdown (GFM)** when standard Markdown is insufficient (e.g., tables, task lists, strikethrough)
+- Avoid raw HTML in content unless absolutely necessary for features that neither standard Markdown nor GFM can express
+- When HTML is required, use semantic elements with `data-type` attributes (e.g., `<div data-type="callout">`) rather than presentational markup
+
+## Images
+
+- Use standard Markdown image syntax: `![alt text](url)`
+- Alt text is required for all images and should describe the content meaningfully
+- Never use raw HTML `<img>` tags in documentation content
+- Images render at their **natural size** by default, centered, capped at `max-width: 100%`
+- Do NOT set an explicit width on images unless the user or design specifically requires it
+- The `ImageBlock` extension defaults to `width: null` (natural size) — do not change this to `100%` or any fixed value
+- Follow Notion's image presentation: centered, natural size, rounded corners, subtle hover shadow
+
+## Screenshots
+
+- All screenshots live in `docs/screenshots/` organized by category (e.g., `features/`, `guides/`)
+- Filenames are descriptive and kebab-case: `slash-menu.png`, `landing-page.png`
+- Each screenshot captures **only the relevant UI element or area**, not a full page, unless the screenshot is specifically meant to show a full page view (e.g., landing page, editor overview)
+- Do not keep unused screenshots — if a screenshot is not referenced in docs content, remove it
+- Do not keep duplicate screenshots under different names
+
+## Asset References in Bundled Docs
+
+- Use the `{{base}}` placeholder for asset paths: `![alt]({{base}}screenshots/features/example.png)`
+- `{{base}}` is resolved at runtime to the correct base URL via `import.meta.env.BASE_URL`
+- Never hardcode absolute paths like `/screenshots/...` or relative paths without `{{base}}`
+
+## Links
+
+- Use standard Markdown link syntax: `[text](url)`
+- Prefer descriptive link text over bare URLs
+- Internal page references use wiki-link style when supported
+
+## Code
+
+- Use fenced code blocks with language tags: ` ```javascript `
+- Use inline code for short references: `` `functionName` ``
+- Mermaid diagrams use fenced code blocks with the `mermaid` language tag
+- Math uses LaTeX: `$$block$$` and `$inline$`

.github/workflows/preview-deploy.yml

@@ -38,6 +38,8 @@ jobs:
           PR_NUMBER: ${{ github.event.pull_request.number }}
           REPO_URL: ${{ github.event.repository.html_url }}
           PRODUCTION_URL: https://nsheaps.github.io/cept/app/
+          VITE_IS_PREVIEW: 'true'
+          HEAD_BRANCH: ${{ github.event.pull_request.head.ref }}
 
       - name: Deploy to GitHub Pages subdirectory
         run: |
@@ -49,8 +51,14 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
           # Fetch gh-pages branch or create it
+          # Discard working tree changes since the build is already complete
+          git checkout -- .
           git fetch origin gh-pages || true
-          git checkout gh-pages || git checkout --orphan gh-pages
+          if git rev-parse --verify origin/gh-pages >/dev/null 2>&1; then
+            git checkout -B gh-pages origin/gh-pages
+          else
+            git checkout --orphan gh-pages
+          fi
 
           # Clean the PR directory and copy new build
           rm -rf "${DEPLOY_DIR}"

.gitignore

@@ -47,6 +47,9 @@ packages/mobile/ios/App/Pods/
 packages/desktop/dist/
 packages/desktop/release/
 
+# Generated at build time (preview deploys)
+packages/ui/src/components/docs/_main-branch-docs.ts
+
 # Logs
 *.log
 npm-debug.log*

docs/content/guides/markdown-extensions.md

@@ -62,9 +62,23 @@ Math uses LaTeX syntax:
 - **Block**: `$$E = mc^2$$`
 - **Inline**: `$a^2 + b^2 = c^2$`
 
+## Images
+
+Use standard Markdown image syntax:
+
+```markdown
+![Alt text describing the image](url)
+```
+
+- Alt text is required for all images
+- Images render at their natural size, centered, capped at the content width
+- Cept does not stretch images to fill the page — small images stay small
+- Use GitHub Flavored Markdown (GFM) conventions when standard Markdown is not sufficient
+
 ## Design Principles
 
-1. **Markdown first** — Standard markdown is preferred for all content that has a natural markdown representation
-2. **HTML fallback** — Rich blocks that extend markdown use HTML with `data-type` attributes
-3. **Interoperability** — Files can be opened in any markdown editor; extended blocks render as HTML
-4. **No proprietary format** — Everything is plain text, never binary or opaque
+1. **Standard Markdown first** — Use standard Markdown syntax whenever possible. This is the default for all content that has a natural Markdown representation.
+2. **GFM fallback** — When standard Markdown is not sufficient (e.g., tables, task lists, strikethrough), fall back to GitHub Flavored Markdown.
+3. **HTML as last resort** — Rich blocks that extend Markdown use HTML with `data-type` attributes. Avoid raw HTML when Markdown or GFM can express the same thing.
+4. **Interoperability** — Files can be opened in any Markdown editor; extended blocks render as HTML.
+5. **No proprietary format** — Everything is plain text, never binary or opaque.