docs: rebuild agentsview.io as a tiered marketing and documentation site (#1568)

Rebuilds agentsview.io as a three-tier site: a hand-written marketing landing page at `/`, a nine-stop guided tour at `/guide/`, and the Zensical documentation moved under `/docs/`. The goal is to pitch AgentsView as the system of record for agent session intelligence — an always-on daemon with monitoring, cost accounting, search, recall, and agent-facing interfaces — rather than a desktop session browser.

## What the site does now

- **Marketing tier** (`docs/website/`): landing page with a two-column hero (headline, install command, and a framed dashboard screenshot), nine numbered sections (record, observe, account, understand, remember, feed back, share, own, start), 56 agent-harness chips, live GitHub stars/version via the API with a cached fallback, and a lightbox for screenshots. `/guide/` walks the session intelligence loop across nine stops. Dark blue theme with vendored Inter and JetBrains Mono (OFL licenses included), a custom AV favicon, and a 404 page.
- **Docs tier**: Zensical builds under `/docs/` via `site_url`, with `docs/index.md` rewritten as a docs landing page (mental model, architecture, privacy). All 28 doc pages' absolute links are rewritten with the `/docs/` prefix. The `docs/agents/` contributor guides are no longer published (they were accidentally reachable before).
- **Machine-readable tier**: every route ships a Markdown twin (`/index.md`, `/guide.md`, `/docs/<page>.md`) advertised by a `rel="alternate" type="text/markdown"` head link and footer links, and `/llms.txt` lists the full twin set.

## Redirects and contracts

`docs/vercel.json` carries 61 permanent redirects covering every legacy route: 28 old root pages (both `/<page>/` and `/<page>.md`) to their `/docs/` locations, asset wildcards, and the pre-existing `/postgresql/`, `/insights/`, and `/architecture/` aliases. The two temporary install-script redirects are unchanged.

The validators enforce the new structure: `check_built_site.py` verifies every route's Markdown twin, alternate link, metadata, and bidirectional `llms.txt` coverage; `check_vercel_redirects.py` now also rejects unexpected redirect entries; `scripts/docs_assets_test.go` covers the assembled three-tier output, including the sitemap shipping at both `/sitemap.xml` and `/docs/sitemap.xml` (Zensical's instant navigation fetches the latter and silently degrades if it 404s).

## Tradeoffs and limits

- The marketing tier is plain HTML/CSS/JS assembled by `zensical-docs.sh` — no new build toolchain or Node dependency.
- Vercel configuration is untouched: the root directory stays `docs/`, output stays `site/`, and deploys remain manual via `make docs-deploy`.
- The docs tier still uses the Zensical default favicon; only the marketing tier has the AV mark.

## Where to look

- `docs/zensical-docs.sh` — the site assembly: docs build into `site/docs/`, then the website tier, `llms.txt`, and sitemap copies are placed at the root.
- `docs/website/index.html` and `docs/website/styles/site.css` — the landing page and theme.
- `docs/scripts/check_built_site.py` — the contracts that keep the twin/llms.txt/redirect structure honest.

Preview locally with `make docs-build && make docs-preview`.


Co-authored-by: Wes McKinney <wesm@users.noreply.github.com>

Author: wesm

Makefile

@@ -552,6 +552,9 @@ docs-build:
 docs-serve:
 	cd docs && bash assets/hydrate-assets.sh && uv run bash ./zensical-docs.sh serve
 
+docs-preview:
+	python3 -m http.server 8000 --directory docs/site
+
 docs-check:
 	bash scripts/check-docs.sh
 

docs/README.md

@@ -1,19 +1,38 @@
 # AgentsView docs maintainer guide
 
-This directory contains the Zensical source for <https://agentsview.io>. The
-docs source lives on `main`; image media lives on orphan asset branches so
-normal clones do not pull screenshots and PNGs into the main history.
+This directory contains the source for <https://agentsview.io>: a hand-written
+marketing tier (`/` and `/guide/`) plus the Zensical documentation tier under
+`/docs/`. The source lives on `main`; image media lives on orphan asset branches
+so normal clones do not pull screenshots and PNGs into the main history.
+
+## Site structure
+
+- `/` and `/guide/`: static marketing pages from `website/`.
+- `/docs/**`: Zensical-rendered documentation from the top-level `*.md` pages.
+- Every published page has a raw Markdown twin: `/index.md`, `/guide.md`,
+  `/docs/index.md`, and `/docs/<page>.md` beside each `/docs/<page>/` route.
+- `/llms.txt`: hand-maintained machine-readable index of the Markdown twins. Add
+  every new public page to `zensical.toml`, `llms.txt`, and
+  `scripts/check_built_site.py` (`DOCS_PAGES`), plus the redirect tables if it
+  replaces an old URL.
+- Legacy root docs URLs (`/quickstart/`, `/usage.md`, `/assets/...`) redirect
+  permanently to their `/docs/` equivalents via `vercel.json`.
 
 ## Layout
 
-- `*.md` and related public subdirectories: public docs source.
-- `internal/` and `superpowers/`: maintainer references excluded from the
-  published site.
+- `*.md`: public docs source, rendered under `/docs/`.
+- `website/`: marketing tier (HTML, CSS, fonts, Markdown twins) copied to the
+  site root at build time.
+- `llms.txt`: machine-readable page index published at the site root.
+- `agents/`, `internal/`, and `superpowers/`: maintainer references excluded
+  from the published site.
 - `zensical.toml`: Zensical site configuration and navigation.
 - `pyproject.toml` and `uv.lock`: pinned docs toolchain.
-- `vercel.json` and `vercel-build.sh`: Vercel project configuration.
+- `vercel.json` and `vercel-build.sh`: Vercel project configuration, including
+  the legacy-URL redirect table.
 - `zensical-docs.sh`: builds from a temporary public-docs copy so maintainer
-  files are excluded from the published site.
+  files are excluded, then assembles the website tier, Markdown twins,
+  `llms.txt`, and root sitemap into `site/`.
 - `assets/hydrate-assets.sh`: hydrates ignored local assets from orphan
   branches.
 - `assets/update-static-assets-branch.sh`: updates curated static assets.
@@ -52,12 +71,21 @@ Hydrate assets and build:
 AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1 make docs-build
 ```
 
-Preview locally:
+Preview the docs tier with live reload (absolute `/docs/` and marketing links do
+not resolve in this mode):
 
 ```bash
 AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1 make docs-serve
 ```
 
+Preview the full assembled site (marketing tier, `/docs/`, Markdown twins) after
+a build:
+
+```bash
+AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1 make docs-build
+make docs-preview
+```
+
 Run docs validation:
 
 ```bash

docs/activity.md

@@ -8,7 +8,7 @@ actually active, how much work overlapped, and which projects, models, agents,
 machines, and sessions contributed to a time window. Open it from the
 **Activity** button in the header or directly at `/activity`.
 
-![Default daily Activity view](/assets/generated/screenshots/activity-page.png)
+![Default daily Activity view](/docs/assets/generated/screenshots/activity-page.png)
 
 The report is built from timestamped session activity and usage rows. It
 includes one-shot and automated sessions by default, then lets you narrow the
@@ -22,7 +22,7 @@ adopts and publishes shared ranges when **Settings > Date ranges > Link date
 ranges across pages** is enabled; a shared range wider than Activity can
 represent is not adopted.
 
-![Weekly Activity view](/assets/generated/screenshots/activity-week.png)
+![Weekly Activity view](/docs/assets/generated/screenshots/activity-week.png)
 
 Additional filters scope the report by:
 
@@ -64,7 +64,7 @@ The **Concurrency** chart shows active agents over the selected range. Blue
 segments represent interactive sessions, orange segments represent automated
 sessions, and the strip below the chart marks active versus idle buckets.
 
-![Weekly Activity concurrency chart](/assets/generated/screenshots/activity-concurrency.png)
+![Weekly Activity concurrency chart](/docs/assets/generated/screenshots/activity-concurrency.png)
 
 Hover a bucket to see its time range, peak agent count, agent-minutes, output
 tokens, and cost. The **Overlay** control can draw an additional **Tokens** or
@@ -82,7 +82,7 @@ The **Sessions** table lists every session that contributed to the report. Rows
 include the session title, model, project, agent, agent-minutes, cost, and
 active window.
 
-![Weekly Activity sessions table](/assets/generated/screenshots/activity-sessions.png)
+![Weekly Activity sessions table](/docs/assets/generated/screenshots/activity-sessions.png)
 
 Click a session title to open that session in the transcript viewer. Column
 headers for **Project**, **Agent**, **Agent-min**, **Cost**, and **Window** are
@@ -102,7 +102,7 @@ The **Breakdown** panel ranks activity by **Project**, **Model**, and **Agent**.
 Toggle between **Agent-min** and **Cost** to change the metric, and use the
 stacked bars to compare interactive and automated contributions.
 
-![Weekly Activity breakdowns](/assets/generated/screenshots/activity-breakdowns.png)
+![Weekly Activity breakdowns](/docs/assets/generated/screenshots/activity-breakdowns.png)
 
 Rows with no value for the selected metric are omitted from that view, so
 cost-only untimed sessions appear in **Cost** but not **Agent-min**.
@@ -117,10 +117,10 @@ model charges, but they still sum to the displayed total.
 
 Worktree layouts the parser does not recognize can surface a branch or worktree
 directory name as a project. Each row in the **Project** breakdown links to that
-project on the [Data page](/data/), where the mapping editor lists the project's
+project on the [Data page](/docs/data/), where the mapping editor lists the project's
 observed session folders, previews the full-archive impact of a folder-path →
 project rule, and applies a
-[worktree project mapping](/configuration/#worktree-project-mappings) rule in
+[worktree project mapping](/docs/configuration/#worktree-project-mappings) rule in
 one atomic step. Cleaning always evaluates the complete archive; the current
 Activity range and filters do not carry over.
 
@@ -131,10 +131,10 @@ At the bottom of the page, **Activity Insight** shows an existing global
 the server is writable, generate a new insight from the same panel using Claude,
 Codex, Copilot, Gemini, or Kiro.
 
-![Weekly Activity Insight panel](/assets/generated/screenshots/activity-insight.png)
+![Weekly Activity Insight panel](/docs/assets/generated/screenshots/activity-insight.png)
 
 The **Open in Generated insights** link opens the
-[Generated insights](/recall/?tab=generated) tab prefilled with the same range.
+[Generated insights](/docs/recall/?tab=generated) tab prefilled with the same range.
 Generation is disabled when the connected server cannot run an agent CLI.
 
 ## CLI And API
@@ -167,8 +167,8 @@ The same paging flags work with `--offline`; the signed direct-mode cursor
 carries the original resolved range and filters, then deterministically
 recomputes that generation before selecting the next page.
 
-See [CLI Reference](/commands/#agentsview-activity-report) and
-[Session API](/session-api/#activity-report) for flags and response shape.
+See [CLI Reference](/docs/commands/#agentsview-activity-report) and
+[Session API](/docs/session-api/#activity-report) for flags and response shape.
 
 ### JSON Contract
 
@@ -247,8 +247,8 @@ row contains an opaque `project_key`. `projects` is keyed by that value and
 carries the presentation-only `display_label`; unknown project identity is
 represented by an explicit `resolution` with `identity` omitted.
 
-See [Token Usage & Costs](/token-usage/#json-contract) for the shared bump
-rules, [Pricing Provenance](/token-usage/#pricing-provenance) for pricing digest
+See [Token Usage & Costs](/docs/token-usage/#json-contract) for the shared bump
+rules, [Pricing Provenance](/docs/token-usage/#pricing-provenance) for pricing digest
 and `cost_source` semantics, and
-[Project Identity](/token-usage/#project-identity) for key derivation and
+[Project Identity](/docs/token-usage/#project-identity) for key derivation and
 redaction notes.