> ## Documentation Index
> Fetch the complete documentation index at: https://notewise.click/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Website and docs

> Work on the NoteWise marketing website and Mintlify documentation site.

The repository ships two public web surfaces:

* `website/` — the marketing site at `https://notewise.click`
* `docs/` — the Mintlify documentation source served at `https://notewise.click/docs`

## Website structure

The website is a TanStack Start/Vite app built with Nitro for deployment to Vercel.

| Path                                     | Purpose                                                           |
| ---------------------------------------- | ----------------------------------------------------------------- |
| `website/src/routes/__root.tsx`          | HTML shell, SEO metadata, JSON-LD, analytics scripts              |
| `website/src/routes/index.tsx`           | Landing page route composition                                    |
| `website/src/routes/install.tsx`         | Smart `/install` route for shell, PowerShell, and browser clients |
| `website/src/routes/sitemap[.]xml.tsx`   | Sitemap route                                                     |
| `website/src/components/SitemapPage.tsx` | Browser-friendly sitemap UI and sitemap link inventory            |
| `website/src/components/sitemapData.ts`  | Shared website/docs URL inventory for sitemap XML and UI          |
| `website/src/components/`                | Page sections and route-level components                          |
| `website/src/ui/`                        | Reusable primitives including both `Terminal` and `FineIcon`      |
| `website/src/server/`                    | Server functions used by the site                                 |
| `website/vite.config.ts`                 | TanStack Start, Nitro, Vite, Tailwind, and path alias config      |

Keep page sections directly under `website/src/components/`. Keep reusable UI primitives outside that folder in `website/src/ui/`.

The `/install` surface is split deliberately: `website/src/routes/install.tsx` handles content negotiation and returns shell or PowerShell bootstrap scripts for CLI clients, while `website/src/components/InstallPage.tsx` renders the browser install page and copy buttons.

The `/sitemap.xml` surface follows the same split: `website/src/routes/sitemap[.]xml.tsx` handles XML versus browser HTML responses, while `website/src/components/SitemapPage.tsx` owns the browser-readable table UI.

## Website workflow

Use Bun for all website work. `website/bun.lock` is the canonical lockfile.

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
cd website
bun install --frozen-lockfile
bun run lint
bunx tsc --noEmit
bun run build
bun run preview
```

Run `bun run build` before `bun run preview`; preview serves the built TanStack output and catches production-only routing issues before Vercel deployment.

## Website quality rules

* Keep SEO metadata honest. Do not add synthetic ratings, fake reviews, or misleading license claims.
* Preserve landmarks, visible focus states, skip links, and descriptive button labels.
* Inherit the system theme on first load. Only a user theme toggle should persist `nw-theme` in local storage.
* Avoid delayed reveal effects that make first paint feel broken or inconsistent.
* Never commit local website env files, Vercel credentials, analytics secrets, OAuth tokens, or provider keys.

## Docs workflow

Mintlify docs live in `docs/`.

| Path               | Purpose                                                       |
| ------------------ | ------------------------------------------------------------- |
| `docs/docs.json`   | Mintlify navigation, redirects, SEO, theme, and site settings |
| `docs/start/`      | Start section pages                                           |
| `docs/use/`        | User workflow pages                                           |
| `docs/config/`     | Configuration pages                                           |
| `docs/operate/`    | Operations and CLI pages                                      |
| `docs/understand/` | Architecture and maintenance pages                            |
| `docs/umami.js`    | Custom JavaScript loaded by Mintlify on docs pages            |

When adding a docs page, add the `.mdx` file under the matching `docs/` section folder and update the `navigation.groups` list in `docs/docs.json`.

Do not run Prettier on docs MDX. Mintlify component children can contain fenced code blocks, and Prettier may rewrite them into parser-breaking forms. For docs-only validation, parse `docs/docs.json` and run `node --check docs/umami.js`.

## Analytics

Both public web surfaces use Umami.

* Website analytics are added in `website/src/routes/__root.tsx`.
* Docs analytics are added through `docs/umami.js`, because Mintlify supports custom JavaScript files in the docs content directory.

Do not add analytics provider blocks to `docs/docs.json` unless the analytics provider intentionally changes.