# Nepal Dev Verse

- Nepal Dev Verse Docs: This documentation site: how it is organised, built and decided.
  - [Nepal Dev Verse Docs](/docs): The documentation platform for packages and projects by Nepalese developers, and how it is organised.
  - Maintain: Decisions, design documents and security documents for this site
    - [Maintainer documentation](/docs/maintain): How this site is built and decided: a map of its decisions, design documents and security documents, and what lives where.

    - **Decisions**
    - Architecture Decision Records
      - [Architecture Decision Records](/docs/maintain/adr): Every decision about how this site is built and run, with its status, from the first ADR to the latest.
      - [ADR-0001 — Every change starts with an approved ADR](/docs/maintain/adr/ADR-0001-adr-driven-development-workflow): Every feature and functional change starts with a written decision, and no implementation begins until the owner approves it.
      - [ADR-0002 — Design documents are living snapshots, published as this site's Maintain track](/docs/maintain/adr/ADR-0002-living-design-documentation): This site's design documents describe it as it stands now and are published as its Maintain track, separate from decisions and package docs.
      - [ADR-0003 — Comments explain why; every branch takes a block](/docs/maintain/adr/ADR-0003-code-comment-policy): Comments explain why and the code explains what, so most code has no comment, and every branch takes a block.
      - [ADR-0004 — Resolve ambiguity by asking, never by guessing](/docs/maintain/adr/ADR-0004-ask-never-guess): Check what can be verified, ask the owner what cannot, with options and a recommendation, and never pick something plausible and move on.
      - [ADR-0005 — Security and privacy are a standing practice](/docs/maintain/adr/ADR-0005-security-as-a-standing-practice): Security and privacy are part of every change: each ADR has a security section, and the owner decides every security and privacy question.
      - [ADR-0006 — Agent skills are advisory; this repository's documentation is binding](/docs/maintain/adr/ADR-0006-agent-skills-are-advisory): Use agent skills freely, but this repository's working agreement and documents are binding, and no skill grants a permission they withhold.
      - [ADR-0007 — Tests are part of every change](/docs/maintain/adr/ADR-0007-tests-are-part-of-every-change): Every change ships tests for its happy path and its obvious failure paths, and a bug fix starts with a test that fails for the bug's reason.
      - [ADR-0008 — A UI change ships an app flow, drawn in Mermaid](/docs/maintain/adr/ADR-0008-a-ui-change-ships-an-app-flow): Any decision that changes what a person sees ships an app flow, with entry points, the flow, a wireframe per screen and each screen's states.
      - [ADR-0009 — Trusted agent skills are vendored in .claude/agent-skills/, routed by an index](/docs/maintain/adr/ADR-0009-trusted-agent-skills-are-vendored): Trusted agent skills are copied into the repository at pinned commits and found through an index, so only reviewed skills are used.
      - [ADR-0010 — Projects document themselves here through a git submodule, one folder each](/docs/maintain/adr/ADR-0010-projects-document-themselves-through-a-submodule): Each project or package includes this repository as a git submodule and writes its own pages into its own folder, with a person committing.
      - [ADR-0011 — Archify diagrams are embedded in pages from sandboxed HTML files](/docs/maintain/adr/ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html): Archify diagrams are committed as a source file and an HTML file, and embedded in pages through a sandboxed frame.
      - [ADR-0012 — Every page in content/docs is MDX](/docs/maintain/adr/ADR-0012-every-page-is-mdx): Every documentation page is an MDX file written as Markdown first, so a page can use a component only where it does something Markdown cannot.
      - [ADR-0013 — Packages and projects share one catalogue shape: two tracks, version lines and demos](/docs/maintain/adr/ADR-0013-packages-and-projects-share-one-catalogue-shape): Packages and projects declare one catalogue entry, with a Use track, a Maintain track and version lines, so every entry is built the same way.
      - [ADR-0014 — The home page is a search-first map of every release](/docs/maintain/adr/ADR-0014-home-page-is-a-search-first-release-map): The decision to make the home page a search-first map of every package, project and release, and which skill builds it.
      - [ADR-0015 — Every package and project lives at the root, in one shape and one look](/docs/maintain/adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look): Every package and project lives at the site's root, at its own short address, with the same folder shape, version lines and look.
      - [ADR-0016 — Home search is the Fumadocs dialog, and private projects render server-side](/docs/maintain/adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side): The home page's search button opens the site's one search dialog, and its private projects are rendered on the server, with Cache Components on.
      - [ADR-0017 — The whole site is one solar system](/docs/maintain/adr/ADR-0017-the-whole-site-is-one-solar-system): The site's single metaphor: the star is the maker, a package is a solid planet, a project a ringed one, and each version line a moon.
      - [ADR-0018 — Docs pages get orbit stations, a trajectory and the full horizon](/docs/maintain/adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon): Docs pages gain a planet row and orbit stations in the sidebar, a trajectory for On this page, and the full Horizon footer.
      - [ADR-0019 — ADR folders show as a constellation in the sidebar](/docs/maintain/adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar): A folder named adr shows in the sidebar as a constellation, with one moon per decision phased by its status, in any package or project.
      - [ADR-0020 — People in ADRs are GitHub usernames, shown as profile chips](/docs/maintain/adr/ADR-0020-people-in-adrs-are-github-usernames-shown-as-profile-chips): Everyone who decides or approves an ADR is written as a GitHub profile link, which the site shows as a chip with their avatar.
      - [ADR-0021 — Tests run with Bun's built-in test runner](/docs/maintain/adr/ADR-0021-tests-run-with-bun-test): Tests run on Bun's built-in test runner, with no test-runner dependency and only Bun's types added, checked like the rest of the code.
      - [ADR-0022 — Diagrams show their Archify view on the page and their Mermaid in Markdown](/docs/maintain/adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown): Every diagram is one component holding a Mermaid fence: pages show its Archify view, and every Markdown surface carries the Mermaid.
      - [ADR-0023 — Sidebar stations open one at a time](/docs/maintain/adr/ADR-0023-sidebar-stations-open-one-at-a-time): At most one sidebar station is open at each level, so opening one closes the one beside it and the sidebar stays short.
      - [ADR-0024 — A project can span several repositories](/docs/maintain/adr/ADR-0024-a-project-can-span-several-repositories): A project made of several repositories lists them in its catalogue, with one primary, and gives each its own folder in each track.
      - [ADR-0025 — The overview has the same sidebar as its tracks](/docs/maintain/adr/ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks): An entry's overview shows the sidebar of its default track, and every track lists Overview as its first item.
      - [ADR-0026 — The moon picker on an overview opens a line's first page](/docs/maintain/adr/ADR-0026-the-moon-picker-on-an-overview-opens-a-lines-first-page): On an overview, choosing a version line in the moon picker opens that line's first page, since the overview itself has one copy.
      - [ADR-0027 — The sidebar is a scale ladder with one lifted orbit](/docs/maintain/adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit): The sidebar is drawn as a ladder of ever smaller bodies, from planet and moon down to belts, orbits and satellites, with only the open orbit lifted.
      - [ADR-0028 — The site is named Puncoz Verse](/docs/maintain/adr/ADR-0028-the-site-is-named-puncoz-verse): The site is named Puncoz Verse, shown in its header, titles and share images, and its own documentation is Puncoz Verse Docs.
      - [ADR-0029 — The Verse is a still sky you zoom through](/docs/maintain/adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through): The Verse is the still sky around the one system: a brand mark, a star field behind every page, and a zoom between its levels.
      - [ADR-0030 — The horizon rises over the page, and its sky comes alive](/docs/maintain/adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive): On docs pages the Horizon footer rises over the sidebar and trajectory, under a living dusk sky whose loops run only while it is on screen.
      - [ADR-0031 — The sidebar sets without dimming](/docs/maintain/adr/ADR-0031-the-sidebar-sets-without-dimming): As the Horizon enters, the sidebar and the trajectory set by dropping into its dusk edge and stay at full opacity.
      - [ADR-0032 — The hero's system comes alive](/docs/maintain/adr/ADR-0032-the-heros-system-comes-alive): The home page's system gains every orbit, a breathing star, planet trails, a lean toward the pointer, a comet and a telemetry line.
      - [ADR-0033 — The footer says you've reached the horizon](/docs/maintain/adr/ADR-0033-the-footer-says-you-have-reached-the-horizon): The footer's closing line becomes "You've reached the horizon. The Verse goes on.", and The Verse links to the Verse view.
      - [ADR-0034 — The proxy answers unknown paths with a true 404](/docs/maintain/adr/ADR-0034-the-proxy-answers-unknown-paths-with-a-true-404): The proxy answers every unknown path with a 404 status and the whole out-of-orbit page from the first request, instead of a blank 200.
      - [ADR-0035 — Every page is ready for search and sharing](/docs/maintain/adr/ADR-0035-every-page-is-ready-for-search-and-sharing): Canonical links, a sitemap, robots rules, structured data, descriptions and designed share images for every page, built from the content.
      - [ADR-0036 — The site is Nepal Dev Verse, part of nepal-dev.com](/docs/maintain/adr/ADR-0036-the-site-is-nepal-dev-verse): The site becomes Nepal Dev Verse, a documentation platform for Nepalese developers, with a summit-and-flag mark and a credit to nepal-dev.com.
      - [ADR-0037 — The Horizon is the Himalaya](/docs/maintain/adr/ADR-0037-the-horizon-is-the-himalaya): The footer's bare curve becomes a range rising out of cloud, with alpenglow from the rising star, the flag raised on arrival and a light for every entry.

    - **Design**
    - Architecture
      - [Architecture](/docs/maintain/architecture): How the site is put together: its content sources, build steps, routes and integrations.
      - [Architecture — puncoz-packages-docs](/docs/maintain/architecture/system): How the site works as built: a Next.js and Fumadocs app rendering content as pages, Markdown, images and search records, with its routes and components.
    - App flows
      - [App flows](/docs/maintain/app-flow): What a person sees and how they move through it, with one file per feature, written with every decision that changes the interface.
      - [App flow — the ADR constellation](/docs/maintain/app-flow/adr-constellation): How an ADR folder's station in the sidebar shows its decisions as a constellation of moons, and each state of it.
      - [App flow — the community identity](/docs/maintain/app-flow/community-identity): Where readers see Nepal Dev Verse: its name, the summit-and-flag mark, the home line, the star's label and the footer's credit.
      - [App flow — diagrams](/docs/maintain/app-flow/diagrams): How a diagram appears on a page: its Archify view in a sandboxed frame that fits it and follows the site's theme.
      - [App flow — docs sidebars: orbit stations, the trajectory and the horizon](/docs/maintain/app-flow/docs-sidebars): What a reader sees around a docs page: the planet row and orbit stations, the trajectory, its bar on phones and the horizon below.
      - [App flow — GitHub profile chips](/docs/maintain/app-flow/github-profile-chips): How a GitHub username in an ADR shows as a chip with its avatar, and what happens when the avatar cannot load.
      - [App flow — the Himalayan Horizon](/docs/maintain/app-flow/himalayan-horizon): How the end of every page looks and behaves with the range on the planet's edge: alpenglow, the flag raised on arrival and a light for every entry.
      - [App flow — home page](/docs/maintain/app-flow/home-page): What a person sees on the home page, section by section: the system, the search button, planet cards, private projects and the rest.
      - [App flow — the Horizon's closing line](/docs/maintain/app-flow/horizon-closing-line): How the Horizon footer's closing line works: it says the reader has reached the horizon, and its link leads to the Verse view.
      - [App flow — the living hero](/docs/maintain/app-flow/living-hero): How the home page's hero behaves: its orbits, living star and trails, the spin-up on arrival, the lean toward the pointer and the comet.
      - [App flow — the living horizon](/docs/maintain/app-flow/living-horizon): How the end of every page behaves: the footer rising over the sidebar and its living sky of stars, clouds and shooting stars over the range.
      - [App flow — multi-repository projects](/docs/maintain/app-flow/multi-repository-projects): What a reader sees of a project made of several repositories: one planet and overview, with a sidebar station for each repository.
      - [App flow — one open station](/docs/maintain/app-flow/one-open-station): How the sidebar's orbit stations open and close, with at most one open beside another at every level.
      - [App flow — the overview's sidebar](/docs/maintain/app-flow/overview-sidebar): What the sidebar shows on an entry's overview: the same sidebar as its default track, with Overview first in every track.
      - [App flow — package and project navigation](/docs/maintain/app-flow/package-navigation): How a reader moves around a package or project: its tracks, version lines and the moves between them, screen by screen.
      - [App flow — search and sharing](/docs/maintain/app-flow/search-and-sharing): What a person sees of a page before opening it: the browser tab, a search result and a shared link's card.
      - [App flow — the sidebar's scale ladder](/docs/maintain/app-flow/sidebar-scale-ladder): How the docs sidebar is drawn as a ladder of smaller and smaller bodies: planet, moon, landmarks, belts, orbits and satellites.
      - [App flow — site pages: root URLs, header and docs pages](/docs/maintain/app-flow/site-pages): What a person sees of the site's structure: the root addresses, the shared header and the docs page layout.
      - [App flow — the solar system](/docs/maintain/app-flow/solar-system): The look every page shares: planet and moon marks, the orrery theme switch, the planet header, the footer and the 404.
      - [App flow — the universe theme](/docs/maintain/app-flow/universe-theme): How the Verse reaches every page, in three stages: its identity and still sky, the zoom between levels, and its words.
      - [App flow — unknown paths](/docs/maintain/app-flow/unknown-paths): What a reader gets at an address that is not a page: the whole out-of-orbit page with a 404 status, on the first request.
    - Product requirements
      - [Product requirements](/docs/maintain/prd): What each reader-facing feature must do, for whom, and how we know it works.
      - [PRD — the ADR constellation](/docs/maintain/prd/adr-constellation): Why long ADR lists in the sidebar became a constellation: the problem, who it is for, and what it must do.
      - [PRD — diagrams](/docs/maintain/prd/diagrams): What diagrams on a page must do for readers: show one clean view on the site's own colours, with Mermaid kept for Markdown.
      - [PRD — docs sidebars: orbit stations, the trajectory and the horizon](/docs/maintain/prd/docs-sidebars): What the sidebars around a docs page must do for readers, so long tracks stay easy to scan and the place on the page is clear.
      - [PRD — home page and catalogue](/docs/maintain/prd/home-page): What the home page and catalogue must do: show what is documented, which version a page covers, and where to go next.
      - [PRD — multi-repository projects](/docs/maintain/prd/multi-repository-projects): What a project made of several repositories needs: one place for its documentation, with each repository writing only its own part.
      - [PRD — search and sharing](/docs/maintain/prd/search-and-sharing): What people searching for or sharing a page should get: the right page, plain words and an image that looks like this site.
      - [PRD — site pages: root URLs, versions, user and maintainer docs, one look](/docs/maintain/prd/site-pages): What the site's structure must do for readers: short addresses, version lines, separate user and maintainer docs, and one look throughout.
      - [PRD — the universe theme](/docs/maintain/prd/universe-theme): Why the site needed a wider sky than one solar system, and what the Verse must do for readers moving between its levels.
    - API
      - [API](/docs/maintain/api): Contracts for every route another client or system calls: Markdown, llms.txt, search records, crawler routes and any future integration.
      - [API — Machine-readable content routes](/docs/maintain/api/content-routes): The contracts of the routes tools read: per-page Markdown, llms.txt, llms-full.txt, Open Graph images, search records and the proxy's redirects.
      - [API — crawler routes](/docs/maintain/api/crawler-routes): The contracts of robots.txt, sitemap.xml, the web manifest, the Apple icon, the share images and the noindex header.
    - Data flow diagrams
      - [Data flow diagrams](/docs/maintain/dfd): Where content and data go on their way through the site, and every trust boundary they cross.
      - [DFD — System (Level 0)](/docs/maintain/dfd/system): The whole site as one data flow, from authoring through the build and publishing to reading, with its trust boundaries.
    - Sequence diagrams
      - [Sequence diagrams](/docs/maintain/sequence): Flows that span several actors or systems, run asynchronously or retry, such as the build and search sync.
      - [Sequence — Build and search sync](/docs/maintain/sequence/build-and-search-sync): What happens when the site is built and published: next build runs, then every page's search record is pushed to Algolia.
    - State machines
      - [State machines](/docs/maintain/state): Lifecycles of things with more than two states or guarded transitions, such as a package version line.
      - [State machine — package version line](/docs/maintain/state/package-version-lifecycle): The states of a package's version line, from dev through latest to an older line, and what moves it between them.
    - ERD
      - [ERD](/docs/maintain/erd): The conventions for documenting persisted data, which must never drift from the code that defines it.

    - **Security**
    - Access control
      - [Access control](/docs/maintain/rbac): Who may read and do what on every surface a page appears on: public readers, people given access to a private project, and the owner.
    - Security
      - [Security](/docs/maintain/security): How this site protects what it holds: security and privacy as part of every change, with its threat model, secrets and audits.
      - [Security audit checklist](/docs/maintain/security/checklist): The full security audits run before the first public deployment and each release, including the checks for each adopted tool.
      - [Data classification](/docs/maintain/security/data-classification): The level given to every piece of content, stored field and outgoing data, and how to handle each one.
      - [Secrets inventory](/docs/maintain/security/secrets): Every environment variable the site reads, whether it is secret, whether it reaches the browser, and where it is used.
      - [Threat model — puncoz-packages-docs](/docs/maintain/security/threat-model): What could go wrong on this site, what is at risk, and how each threat is handled, with private documentation as the main concern.

    - **Templates**
    - Templates
      - [Templates](/docs/maintain/_templates): A starting point for each kind of document: copy one into its directory, fill it in and delete what does not apply.
      - [ADR-NNNN — <short imperative title>](/docs/maintain/_templates/adr): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [API — <route or resource>](/docs/maintain/_templates/api): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [App flow — <feature>](/docs/maintain/_templates/app-flow): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [Architecture — <system or feature>](/docs/maintain/_templates/architecture): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [DFD — <system (Level 0) or feature (Level 1/2)>](/docs/maintain/_templates/dfd): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [ERD — <system or feature subset>](/docs/maintain/_templates/erd): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [PRD — <feature name>](/docs/maintain/_templates/prd): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [RBAC — <feature>](/docs/maintain/_templates/rbac): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [Security — <feature>](/docs/maintain/_templates/security): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [Sequence — <flow name>](/docs/maintain/_templates/sequence): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.
      - [State machine — <entity>](/docs/maintain/_templates/state): Replace this with one or two plain sentences, about 160 characters at most, saying what the page is for.