Edit this directory to update https://agentsview.io. The homepage and guide
are HTML pages under website/. Zensical turns the public Markdown guides into
pages under /docs/.
Follow the documentation style. Check claims
against source, and use release tags to distinguish shipped behavior from newer
main changes. Update each website page's Markdown companion when changing its
copy. Keep plans and historical decisions in the unpublished maintainer
directories below.
Text lives on main. Images live on separate asset branches so normal clones do
not download screenshots and other large media.
/and/guide/: static marketing pages fromwebsite/./docs/**: Zensical-rendered documentation from the top-level*.mdpages.- Every published page has a raw Markdown twin:
/index.md,/guide.md,/docs/index.md, and/docs/<page>.mdbeside each/docs/<page>/route. /llms.txt: hand-maintained machine-readable index of the Markdown twins. Add every new public page tozensical.toml,llms.txt, andscripts/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 viavercel.json.
*.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/, andsuperpowers/: maintainer references excluded from the published site.zensical.toml: Zensical site configuration and navigation.pyproject.tomlanduv.lock: pinned docs toolchain.vercel.jsonandvercel-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, then assembles the website tier, Markdown twins,llms.txt, and root sitemap intosite/.assets/hydrate-assets.sh: hydrates ignored local assets from orphan branches.assets/update-static-assets-branch.sh: updates curated static assets.screenshots/: Docker/Playwright screenshot generator and generated asset branch updater.scripts/check_built_site.pyandscripts/check_vercel_redirects.py: post-build validation.
docs/assets/static/, docs/assets/generated/, docs/site/, docs/.venv/,
and docs/zensical-public-docs.* are ignored local outputs.
docs-assets: curated static media, including the architecture diagram and Open Graph image.docs-generated-assets: generated UI screenshots.
Docs pages should reference media through:
/assets/static/...for curated assets./assets/generated/...for generated screenshots.
Do not commit image media to main.
Install the docs toolchain:
make docs-installHydrate assets and build:
AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1 make docs-buildPreview the docs tier with live reload (absolute /docs/ and marketing links do
not resolve in this mode):
AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1 make docs-servePreview the full assembled site (marketing tier, /docs/, Markdown twins) after
a build:
AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1 make docs-build
make docs-previewRun docs validation:
AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1 make docs-checkWithout AGENTSVIEW_DOCS_USE_LOCAL_ASSET_BRANCHES=1, hydration force-fetches
origin/docs-assets and origin/docs-generated-assets to avoid stale local
asset refs.
Regenerate screenshots and update the local docs-generated-assets orphan
branch:
make docs-generated-assets-branchPush that branch when generated screenshots should be published:
bash docs/screenshots/update-generated-assets-branch.sh --pushFor the initial import or a manual refresh from an existing directory:
bash docs/screenshots/update-generated-assets-branch.sh \
--source docs/assets/generated --pushHydrate or stage curated media under ignored docs/assets/static/, then update
the local docs-assets orphan branch:
make docs-assets-branchPush it only when curated static assets should be published:
bash docs/assets/update-static-assets-branch.sh --pushThe Vercel project should be linked from the repository root with docs/ as the
Vercel root directory:
| Setting | Value |
|---|---|
| Framework preset | Other |
| Root directory | docs |
| Install command | uv sync --frozen --no-dev |
| Build command | uv run --frozen bash ./vercel-build.sh |
| Output directory | site |
Link the checkout once from the repository root:
vercel linkDeploy committed docs changes with:
scripts/update-docs.shCreate a Vercel preview/staging deployment before production with:
make docs-deploy-stagingUse make docs-deploy directly only when the asset branches and local build
state are already correct.