Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
7 changes: 6 additions & 1 deletion .agents/skills/topo-story-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,18 +46,23 @@ Commit the source and authored story together. Build or refresh the generated
site, preview the committed story, and inspect it locally:

```sh
npm exec --no -- topo scan .
npm exec --no -- topo init .
npm exec --no -- topo story preview . stories/example.topo.json
npm exec --no -- topo serve .
```

Home inventories all committed supported stories, not only the preview target.
Scanning is optional for generated Repository exploration.
Open `/stories/<story-id>/`. If source changes later, rerun validation before
previewing and preserve identity plus unrelated authored intent during repairs.
Humans review the authored explanation and generated view; they do not edit the
renderer output in `.topo/cache/site`.

Commit only when authorized by the repository owner. For a globally installed
CLI, use `topo` directly instead of `npm exec --no -- topo`.
Source-grounded native rendering requires the repository's Git `origin` remote
for evidence validation. Do not invent a remote. Initialization and anchor-free
capability demos do not require one; demos must never replace factual evidence.

## Minimal source-grounded document

Expand Down
13 changes: 10 additions & 3 deletions .agents/skills/topo/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,28 @@ Corepack, model service, account or renderer download is needed.
Use `npm exec --no -- topo init . --skills` for opt-in project context.
Identical context files are preserved; differing files and symlinks fail
explicitly. Do not overwrite existing skills/instructions or use a force flag.
Without `--skills`, init only initializes the workspace.
2. Run `npm exec --no -- topo scan .`. It scans TypeScript/JavaScript and renders
Both forms create a ready-to-serve diagram home without analysis, rendering
or browser/server launch, even in an empty/unborn repository. Repeated init
preserves authored context and the existing generated site.
2. Optionally run `npm exec --no -- topo scan .`. It scans TypeScript/JavaScript and renders
committed stories plus Repository exploration. It never invokes a model.
Unsupported/unresolved source fails; an explicitly requested `--allow-partial`
preview is visibly partial and exits 2, not success.
3. Read [story authoring](../topo-story-authoring/SKILL.md). Author/refine a focused
explanation from source evidence. Validate drafts; commit only with the
repository owner's authority, then scan/preview the committed story.
4. Run `npm exec --no -- topo serve . --port 4173`. Review the printed loopback
URL: Repository canvas, story navigation, source evidence, theme and exports.
URL: Home inventory, optional Repository exploration, story navigation,
source evidence, theme and exports. Serve works immediately after init.
Stop your server when finished; never kill another user's listener.
5. Run `npm exec --no -- topo bundle . --output ./site-output --base-path /architecture/`.
Serve the output with a static server. Hosting, access control and uploading
are separate owner decisions. Preserve all emitted license notices.

The init-first home is an unreleased source/local-candidate feature; public
npm 0.1.0 predates it. Use a candidate containing this change, not a claim that
the existing registry version was updated.

`topo enrich` is a separate, explicitly configured provider-command workflow for
secondary commentary. It is not required for source-grounded story editing.
Never execute an unknown enrichment command or claim inferred commentary is fact.
Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ publication remains a separate release-owner action.

### Added

- Create a ready-to-serve, branded diagram Home on plain or skills-enabled
`topo init`, including empty/unborn repositories without scanning. Reuse the
categorized inventory across Home and native story pages, keep Repository
exploration selectable and old deep links working, and bundle truthful
unscanned sites with notices. This is unreleased; public npm 0.1.0 is unchanged.

- Add GitHub-only publication of verified tarballs: normal OIDC and explicit
first-package bootstrap through version/commit-bound tags, with a UI-managed
token exposed only to its publish step. No local npm authentication is needed.
Expand Down
35 changes: 21 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,12 @@
A local-first, deterministic code-architecture visualizer.

```
scan -> generate -> publish
init -> serve -> author / scan -> bundle
```

Scan a repository, build a canonical graph, publish a self-contained static site
into `.topo/`. No hosted service, no telemetry, no account.
Initialize a repository to create a ready-to-serve static diagram home in
`.topo/`. Add authored stories or scan supported source when needed.
No hosted service, no telemetry, no account.

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
Expand All @@ -24,17 +25,18 @@ everything a human adds is recorded as such.

## Install the toolbelt

After publication, install `@jdylanmc/topo-code@0.1.0` in your project, then run
The public `@jdylanmc/topo-code@0.1.0` predates the init-first home described
here. Use a locally built candidate tarball for this unreleased behavior; no
version bump or publication is implied. After installing the candidate, run
`npm exec --no -- topo init . --skills`. This adds project-local Topocode skills
and instructions without replacing existing files. Read
`.agents/skills/topo/SKILL.md`, scan, author/validate stories, preview and bundle
using the installed CLI. Plain `topo init` keeps workspace-only behavior.
Before publication, install both candidate tarballs in one npm command:
`.agents/skills/topo/SKILL.md`, serve, author/validate stories, preview and bundle
using the installed CLI. Plain `topo init` creates the same site without skills.
Install both candidate tarballs in one npm command:

```sh
npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz
npm exec --no -- topo init . --skills
npm exec --no -- topo scan .
npm exec --no -- topo serve .
```

Expand All @@ -53,11 +55,14 @@ From this checkout, with Node.js 22+ and Corepack:
corepack yarn install --immutable
node scripts/bootstrap-renderer.mjs /path/to/jdylanmc-topo-archify-0.1.0.tgz
corepack yarn build
corepack yarn topo scan /absolute/path/to/a/typescript-repository
corepack yarn topo serve /absolute/path/to/a/typescript-repository
corepack yarn topo init /absolute/path/to/a/repository
corepack yarn topo serve /absolute/path/to/a/repository
```

Open the printed address. The default **Repository** view drills from packages
Open the printed address. **Home** is the diagram inventory, initially empty.
Initialization works with an empty/unborn Git repository, invokes no scanner,
model or native renderer, and starts no server or browser automatically.
Run `topo scan` to add **Repository** exploration, which drills from packages
and directories into files, classes, functions, and other compiler declarations.
Each scope is a bounded, source-backed Archify diagram; breadcrumbs, pagination,
source evidence, and deep links work without a server-side query service.
Expand Down Expand Up @@ -88,9 +93,10 @@ includes Topocode, Archify MIT, third-party, and JetBrains Mono SIL OFL 1.1
notices. Deployment, upload, public URLs, and authentication remain the hosting
owner's responsibility.

`topo scan` renders every committed source-grounded story under
`topo scan` renders every supported committed story under
`/stories/<story-id>/`; `topo story validate` checks an uncommitted authored
draft, and `topo story preview` refreshes one committed story. The retired
draft, and `topo story preview` refreshes the inventory and all committed
stories without requiring a scan. The retired
WebGL explorer is not generated or bundled. See the
[local agent authoring workflow](./docs/story-authoring.md),
[catalogue configuration](./docs/story-catalogue.md), the
Expand Down Expand Up @@ -129,7 +135,8 @@ node /absolute/path/to/topo-code/packages/cli/dist/main.js scan "$PWD"
```

Documentation uses `topo` as shorthand for that built entry point. The supported
input is a local Git repository containing TypeScript/JavaScript. Unknown
input for scanning is a local Git repository containing TypeScript/JavaScript.
Initialization and authored stories do not require scannable source. Unknown
configuration, unresolved local/workspace imports and incomplete scans fail
explicitly. An intentional `--allow-partial` preview is visibly non-authoritative
and exits **2**, not success. See the [scanner contract](./docs/scanner.md).
Expand Down
21 changes: 11 additions & 10 deletions distribution/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,15 @@ model invocation during scanning. The exact renderer dependency is
`@jdylanmc/topo-archify@0.1.0`, containing pristine upstream Archify **3.0.0**.

```sh
npm install --save-dev @jdylanmc/topo-code@0.1.0
npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz
npm exec --no -- topo init . --skills
npm exec --no -- topo scan .
npm exec --no -- topo serve .
npm exec --no -- topo bundle . --output ./site-output --base-path /architecture/
```

These registry commands apply **after publication**. For local candidates:

```sh
npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz
```
The init-first Home described here is **unreleased**. The already-public
`@jdylanmc/topo-code@0.1.0` predates it; use a local candidate containing this
change. No registry update or version bump is implied.

Installing both tarballs in the same command satisfies the exact renderer
dependency normally, without a fake registry, workspace links or source checkout.
Expand All @@ -30,17 +27,21 @@ existing instructions, skills, authored stories or config. Identical files are
preserved; differing destinations or symlinks fail explicitly. After a package
upgrade, compare and deliberately reconcile installed context before retrying.
An interrupted copy may leave new files; rerun safely, never force overwrite.
Plain `topo init` retains its existing workspace-only behavior.
Plain `topo init` creates the same ready-to-serve Home without skills. Both
forms work on empty/unborn repositories, invoke no scanner/model/native renderer,
and start no server/browser. Repeating init preserves the current site.

Read the installed skills. Author `stories/**/*.topo.json` from actual source.
`topo story validate . stories/example.topo.json` accepts drafts; preview requires
committed stories. Preserve story/section/anchor identities when source moves.
Commit only with owner authority, then scan and
Commit only with owner authority, then run
`topo story preview . stories/example.topo.json`.
Validation proves structure and anchor resolution, not semantic accuracy.
Before/after source-change examples ship in `examples/story-authoring/`.

The default Repository canvas exposes compiler/static evidence, not inferred
Home is the categorized diagram inventory, initially empty. Preview refreshes
all committed supported stories. Optional `topo scan .` adds a selectable
Repository canvas exposing compiler/static evidence, not inferred
runtime behavior. Partial previews exit 2. `topo enrich` is a separate explicit
provider-command surface, not part of scanning. Generated `.topo/cache` output
is disposable; configuration and authored documents are not.
Expand Down
4 changes: 3 additions & 1 deletion distribution/topo.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ Read `.agents/skills/topo/SKILL.md` and
`.agents/skills/topo-story-authoring/SKILL.md` before authoring Topocode content.
Read `.agents/skills/topo-archify-maintenance/SKILL.md` before renderer maintenance.
Use the installed `topo` executable (`npm exec --no -- topo ...` for a local
installation). Scan is model-free. Authored stories and configuration are source;
installation). Init creates a ready-to-serve Home inventory without scanning or
rendering; preview refreshes all committed stories. Scan adds selectable
Repository exploration and is model-free. Authored stories and configuration are source;
`.topo/cache` is disposable generated output. Preserve existing story/section/
anchor identities and unrelated intent. Successful structural/anchor validation
does not prove semantic truth. Never rewrite generated renderer output as source.
8 changes: 7 additions & 1 deletion docs/npm-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@
Issue [#13](https://github.com/jdylanmc/topo-code/issues/13) ships one practical
CLI-plus-skills toolbelt, not a public SDK. Initial candidate versions:

**Init-first Home is unreleased.** The already-public 0.1.0 predates this change.
Locally built 0.1.0 candidate tarballs can prove the change without changing
registry contents; do not republish that version or imply it contains this fix.

| npm package | Version | Upstream runtime |
| --- | --- | --- |
| `@jdylanmc/topo-archify` | 0.1.0 | Archify 3.0.0, `9286c3b9c2cef359e98586b420d769d87bcb163f` |
Expand Down Expand Up @@ -68,7 +72,9 @@ composed legal notices. Debug source maps and tests do not ship.
agent instructions or authored files. Differing files/symlinks are explicit
conflicts; identical files allow repeat setup. It preflights all destinations
before copying context. Files use exclusive creation; an interruption may leave
new files but never replaces old files. Plain init remains unchanged.
new files but never replaces old files. Both init forms now create the same
minimal branded Home with notices; skills remain opt-in. No scan, model,
source analysis, renderer invocation, server or browser launch occurs in init.

## Release owner gate

Expand Down
Loading
Loading