Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
7756763
feat(site): add Blueprint public website
jdylanmc Oct 1, 2026
d7676ec
feat(stories): draft curated module maps
jdylanmc Oct 1, 2026
7c607bb
feat(demo): publish curated local module stories
jdylanmc Oct 1, 2026
4a6e03c
fix(viewer): preserve nested theme ownership
jdylanmc Oct 1, 2026
28b8024
fix(stories): keep module maps readable
jdylanmc Oct 1, 2026
2df7777
test(catalogue): retain native workflow selector
jdylanmc Oct 1, 2026
6f1304e
test(demo): enforce readable desktop map bounds
jdylanmc Oct 1, 2026
21da329
fix(diagrams): avoid adjacent-row routing detours
jdylanmc Oct 1, 2026
527ce10
feat(stories): add responsibility and execution lenses
jdylanmc Oct 1, 2026
ccfce07
test(lenses): cover semantic exports and failure evidence
jdylanmc Oct 1, 2026
a722f5a
test(catalogue): identify the authoring-loop story
jdylanmc Oct 1, 2026
6d29c2a
fix(lenses): keep responsibility labels readable
jdylanmc Oct 1, 2026
cbeaa8f
feat(stories): add public-surface drilldowns
jdylanmc Oct 1, 2026
ebe64a1
docs(sequence): show the repository collaboration boundary
jdylanmc Oct 1, 2026
df93e28
fix(diagrams): clarify surfaces and sequence framing
jdylanmc Oct 1, 2026
a7c85ed
fix(viewer): bound sequence framing and evidence cards
jdylanmc Oct 1, 2026
4a9c5f7
fix(navigation): preserve native sequence focus details
jdylanmc Oct 1, 2026
8a53c88
test(website): scroll embedded controls into view
jdylanmc Oct 1, 2026
56a6c70
docs(algorithms): add three source-backed sequences
jdylanmc Oct 1, 2026
196b7f4
fix(sequence): trim unused compact viewer padding
jdylanmc Oct 1, 2026
d59b15c
test(viewer): measure settled sequence layouts
jdylanmc Oct 1, 2026
d357985
docs(algorithms): name initiators and their goals
jdylanmc Oct 1, 2026
77f164a
feat(website): embed the collaboration demo on home
jdylanmc Oct 1, 2026
c9363d3
feat(home): show only the native diagram viewer
jdylanmc Oct 1, 2026
648c7ac
feat(sequence): allow authored participant spacing
jdylanmc Oct 2, 2026
e16d480
docs(demo): emphasize understanding code at a glance
jdylanmc Oct 2, 2026
58ef705
fix(sequence): omit redundant native node index
jdylanmc Oct 2, 2026
d6ce584
test(website): isolate terrain motion from demo pixels
jdylanmc Oct 2, 2026
229e566
docs(demo): simplify scan-to-diagram review loop
jdylanmc Oct 2, 2026
aacf9ee
ci(website): prepare automatic Pages deployment
jdylanmc Oct 2, 2026
0110370
Merge remote-tracking branch 'origin/main' into jdylanmc/public-site
jdylanmc Oct 2, 2026
4f09fdb
docs(agents): maintain site and diagrams in the same PR
jdylanmc Oct 2, 2026
29e0448
fix(stories): preserve drilldown identity and origin
jdylanmc Oct 2, 2026
50fa99d
fix(renderer): omit unused identity navigation
jdylanmc Oct 2, 2026
394c93c
fix(stories): retain normal focus link navigation
jdylanmc Oct 2, 2026
9cb1e21
fix(viewer): reconcile grouped diagram navigation
jdylanmc Oct 2, 2026
e659031
fix(stories): restore caption and pane readability
jdylanmc Oct 2, 2026
e6b899f
fix(diagrams): separate source captions from titles
jdylanmc Oct 2, 2026
a6396ad
fix(site): preserve reading width at sidebar transitions
jdylanmc Oct 2, 2026
f20b411
fix(site): preserve return controls at sidebar transitions
jdylanmc Oct 2, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions .github/workflows/website.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
name: Public website

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: public-website-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
pages: read
defaults:
run:
working-directory: topocode
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
path: topocode
fetch-depth: 0
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
repository: jdylanmc/topo-archify
ref: b94790e99e2ca51fcdb74a9bd0f10f637856f92f
path: renderer
fetch-depth: 0
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version-file: topocode/.node-version
- run: corepack enable
- run: yarn install --immutable
- name: Prepare pinned renderer
run: |
node ../renderer/integrations/topo-npm/pack.mjs ../renderer/dist
node scripts/bootstrap-renderer.mjs ../renderer/dist/jdylanmc-topo-archify-0.1.0.tgz
- run: yarn lint
- run: yarn build
- run: yarn workspace @topo/site exec playwright install --with-deps chromium
- run: yarn website:test
- name: Configure Pages
id: pages
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
- name: Build publication artifact
env:
PAGES_BASE: ${{ steps.pages.outputs.base_path }}
run: |
if [ "${GITHUB_REF}" = "refs/heads/main" ] && [ "${GITHUB_EVENT_NAME}" != "pull_request" ]; then
SITE_BASE_PATH="${PAGES_BASE%/}/" yarn website:build
else
yarn website:build
fi
- uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
with:
path: topocode/dist/public-site

deploy:
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
concurrency:
group: github-pages
cancel-in-progress: false
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy website
id: deployment
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
8 changes: 8 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,14 @@ Read relevant existing records before exploration. These files are created
lazily through separately authorized domain recording, not during setup.
See `docs/agents/domain.md`.

### Website and diagram maintenance

When changing Topocode, update affected documentation and curated diagrams in
the same PR. Re-read changed source before updating diagram evidence; never
refresh hashes blindly. If no updates are needed, briefly explain why in the PR.
Existing CI checks evidence and site builds; humans review whether diagrams
explain the code clearly. Keep the curated set small and question-driven.

### Commit messages

Use the terse Conventional Commits policy in `docs/agents/commit-style.md`,
Expand Down
24 changes: 24 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,30 @@ versions are independent; publication remains a separate release-owner action.

## Unreleased

### Added

- Add the public static website with repository-backed documentation, installation
guidance, a curated roadmap, and a live diagram demonstrating the scan-to-review
collaboration. GitHub Actions validates changes and deploys main to GitHub Pages.
See #74 and #75.
- Add eight source-backed self-documentation stories, including module interfaces
and algorithm sequences, with explicit drilldowns and visible return navigation.
- Let authors select a published story subset, add short Architecture captions and
semantic responsibility roles, and request wider Sequence participant spacing.
These repository-build capabilities are not yet in the npm 0.2.0 release.

### Fixed

- Keep default Architecture source captions readable across sidebar breakpoints
without changing authored summary styling. Reserve space for open evidence
rather than covering diagram titles or navigation controls.
- Preserve the actual caller through nested story returns and reloads, and keep
drilldown/focus navigation working for all legal authored section IDs across
native and Graphviz viewers.
- Keep adjacent diagonal Architecture routes local instead of taking unnecessary
detours. Preserve readable captions, interactive accessibility, nested theme
ownership, and source evidence while leaving the pinned renderer unchanged.

## 0.2.0 - 2026-09-30

Release preparation date; npm publication is not implied by these notes.
Expand Down
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,15 @@ The goal is to put a software engineer in the human-in-the-loop position: every
claim the tool makes about a codebase is backed by evidence you can follow, and
everything a human adds is recorded as such.

> **Release preparation: 0.2.0.** The scan-to-site workflow, deterministic reports,
> **Released: 0.2.0.** The scan-to-site workflow, deterministic reports,
> source-grounded stories, static analysis modules, optional AI commentary, and
> pinned Archify 3.0.0 rendering are implemented. Topo is the storybook for
> architects: the generated shell inventories every diagram while preserving
> real Archify viewers. This source prepares the next minor release; registry
> publication remains a separate release-owner step.
> real Archify viewers. Install the published package from npm.

## Install the toolbelt

Once 0.2.0 is published, install the public package below. Its exact
Install the public package below. Its exact
`@jdylanmc/topo-archify@0.1.0` dependency is installed automatically; no source
checkout or paired tarball is required. Then run
`npm exec --no -- topo init . --skills`. This adds project-local Topocode skills
Expand All @@ -48,6 +47,9 @@ npm exec --no -- topo serve .

See [package bootstrap, consumer proof and release procedure](./docs/npm-release.md).

See the [getting-started guide](./docs/getting-started.md), [CLI reference](./docs/cli.md),
and [public website build/deployment guide](./docs/public-website.md).

## Run locally

For the separately preserved, non-integrated prototype, see the
Expand Down
54 changes: 54 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# CLI reference

Run commands inside your project using `npm exec --no -- topo`, or use `topo`
directly after a global installation. Node.js 22+ and a Git repository are
required. Repository arguments default to the current directory where shown.

```text
topo init [repository] [--skills]
topo scan [repository] [--allow-partial] [--responsibilities path]
topo ingest <repository> <report.json> [more.json ...]
topo enrich [repository]
topo preview <repository> <story>
topo story validate <repository> <story>
topo story preview <repository> <story>
topo serve [repository] [--port 4173]
topo bundle [repository] [--output directory] [--base-path /path/]
```

| Command | Purpose |
| --- | --- |
| `init` | Create configuration and a ready-to-serve Home without scanning. `--skills` opts into local agent guidance. |
| `scan` | Generate structural evidence and repository exploration; render committed stories. Strict by default. |
| `ingest` | Ingest normalized report evidence against a clean scanned revision. |
| `enrich` | Explicitly run the repository-configured external command for inferred commentary. Never runs as part of scan. |
| `story validate` | Validate an authored draft and resolve its source anchors. |
| `story preview` | Render committed stories and refresh Home without requiring a scan. |
| `preview` | Legacy shorthand for story preview. |
| `serve` | Serve locally on `127.0.0.1`; default port is 4173. |
| `bundle` | Emit static files with all required runtime assets and notices. |

`--help` (or `-h`) prints the installed CLI contract. Unknown commands, arguments,
and unsupported option combinations fail explicitly.

## Important options

`scan --allow-partial` publishes a visibly incomplete preview and returns exit
code **2**. It is not a success override. Explicit Rust/Tauri analysis currently
requires this acknowledgement.

`scan --responsibilities <path>` accepts an explicit responsibility-grouping
proposal. See [logical architecture](./logical-architecture.md).

`bundle --base-path` must be `/` or an absolute URL path ending in `/`. It creates
that path beneath the output directory. Default output is `.topo/bundle`.

`serve --port 0` requests an available port; use the printed URL.

## Related contracts

- [Configuration and workspace lifecycle](./workspace.md)
- [Story authoring](./story-authoring.md)
- [Report ingestion](./reports.md)
- [Explicit enrichment](./enrichment.md)
- [Rust/Tauri support and limits](./rust-tauri.md)
88 changes: 88 additions & 0 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Get started with Topocode

Topocode is a local-first architecture storybook. Initialize a working Home,
then curate explanations of your code with your coding agent. Scanning is
optional; it supplies structural evidence, not a finished architectural narrative.

## Install

You need **Node.js 22 or newer** and **Git**. Run these commands inside your
project's Git repository:

```sh
npm install --save-dev @jdylanmc/topo-code@0.2.0
npm exec --no -- topo init . --skills
npm exec --no -- topo serve .
```

Open the loopback address printed by the CLI. You have a functional, empty Home.
No scan, model invocation, account, or first Git commit is required to initialize.
The `--no` option prevents `npm exec` from downloading an unexpected package.

`--skills` installs project-local guidance for your agent. Existing identical
files are preserved; conflicting files are reported rather than overwritten.
Omit `--skills` if you only want the storybook.

## Make one useful map

Ask your agent a focused question: “Explain how a request reaches the database,”
or “Show the decisions and failure paths in this workflow.”

Have the agent read the actual source and the installed
`.agents/skills/topo-story-authoring/SKILL.md`. Work together on one story under
`stories/**/*.topo.json`. Review its explanation and evidence, not just its looks.

```sh
npm exec --no -- topo story validate . stories/request.topo.json
```

Validation accepts uncommitted drafts. Once you have reviewed and committed the
source, configuration, and story, render it:

```sh
npm exec --no -- topo story preview . stories/request.topo.json
npm exec --no -- topo serve .
```

Preview refreshes the inventory of committed stories, not only the selected file.
See [working with an agent](./story-authoring.md) and the
[story contract](./story-preview.md).

## Optionally scan the repository

```sh
npm exec --no -- topo scan .
```

The default scanner analyzes TypeScript and JavaScript. Scanning adds repository
exploration; it never invokes a model. Unknown or unresolved source fails
explicitly rather than turning assumptions into edges.

[Rust and Tauri](./rust-tauri.md) require explicit configuration and remain
partial. Their intentional partial preview uses `--allow-partial` and exits
**2**, not success. Do not make CI ignore all scan failures.

## Share a static storybook

```sh
npm exec --no -- topo bundle . --output ./site-output --base-path /architecture/
```

The deployable site is under `site-output/architecture/`. Serve `site-output`
with your static host and open `/architecture/`. Use `/` for a domain-root
deployment. Include every emitted asset and license notice.

No Topocode server is needed for the published bundle. Generated `.topo/cache`
content is disposable; source, configuration, and authored stories are durable.
See [workspace lifecycle](./workspace.md).

## Know what validation proves

Valid anchors show that cited evidence exists. Hash-bound anchors detect source
changes. Neither check proves that a narrative is meaningful, correct in every
detail, or complete. Review maps with a person who knows the system, and repair
the explanation when the implementation changes.

The public self-demo starts with an internal-module map and a companion showing
external dependencies grouped by role. We curate these maps together instead
of publishing development fixtures as an architectural tour.
Loading
Loading