nessalabs / nessa-docs

# nessaDocs
Turn a project's source code into readable system maps and flows, then browse
those maps locally. Your coding agent writes Markdown in your project's
`docs/state`. Nessa Docs renders it with diagrams you can navigate, drag and zoom.
This repository contains the **nessa-docs authoring skill** and the **local web
app**. It works with any project; it does not need the Nessa agent backend.
The current app is a website running on your computer. A Codex extension is a
future integration, not part of this release.
## Start the app
Use Node.js 22.13 or newer within 22.x, 24.x, or 26 and newer, on macOS or Linux.
Native Windows support needs a filesystem adapter and is outside this release.
The recorded browser and local filesystem checks ran on macOS.
 [code] 
Open localhost:4311. Choose **Browse example** to try the
small store map. On macOS, **Browse…** opens the native folder chooser and fills
the project field. Choose **Open project** to load its documentation. You can
also paste an absolute folder path; Linux uses path entry in this release.
The folder must contain `docs/state/README.md`.
The app reads your local files. It does not upload your project, run your agents,
change documentation or execute the state machines shown in diagrams.
## Install the skill
Copy the skill folder into your coding agent's skill directory. For Codex,
install it in the project where you want to write documentation:
 [code] 
Run that command from this checkout. Other agents can read
SKILL.md directly or use their own skill installation
mechanism. Installing the skill does not install or start the web app.
Ask the agent in your project:
> Use $nessa-docs to map this project's system and important user flows in
> docs/state. Read the actual source, explain the main states and decisions in
> plain English, and mark examples, proposals and anything you could not verify.
Start with the parts you need to understand, or ask for a full-project sweep.
Small projects should get a small map. The skill explains how to choose states,
component maps and short sequences without turning the documentation into a code
trace. It also helps update the owning page when behavior changes.
## Browse your project
Open the project in the app after your agent creates its Markdown. Start at the
system map and choose a box with a **+** to open a deeper page or an explanation.
The sidebar is another way to navigate. It resizes up to 350 px.
**Diagrams** shows the page's charts. **Details** shows its complete Markdown,
including short sequences and source references. Drag the diagram surface to
move around; use its zoom and Fit controls to find your place.
**Settings** contains appearance, diagram detail and documentation Health.
To open another project, use **Settings → General → Project**.
Standard shows a short explanation; Full displays the complete authored section.
These choices do not generate content or launch an agent. Sources are collapsed
at the bottom of each page.
Project sel