Build a Project Knowledge Map from Markdown with Source Evidence

What is a source-linked project atlas?

Project Atlas Studio v1.0.0 turns reviewed Markdown links or structured JSON into a local, editable relationship map. Nodes represent decisions, people, documents, milestones or risks; each node and relationship retains a source, line and excerpt. Search, type filters and directed or undirected path tracing help a reader navigate recorded connections. The package is USD 4.99 individually; browser editing and exports need no API key or paid service.

It checks provenance consistency, not whether a claim is true or an inferred dependency makes sense. It does not crawl folders, infer relationships from prose, edit original source files or provide shared access control. A portable atlas contains the source texts, so review them before sharing.

Write explicit links with a direction you can explain

Open the package’s studio.html in a modern browser. Read references/notes.md and save the fictional Markdown below as launch.md. A level-one heading defines an entity with a stable ID, label, type, state and summary, separated by “ | ”. Each following [[target-id|relationship label]] belongs to that entity until the next heading. A link can target an entity in another imported file.

• Here launch → review means “launch depends on review”, and review → checklist means “review uses checklist”. Do not reverse the arrows just to make the layout attractive. A repeated name without an explicit link does not create a relationship.
• Import Markdown accepts up to 20 small files. Browser uploads are limited to 20 KB per file; normalized sources are limited to 16,000 characters each, with at most 80 sources, 80 entities, 180 relationships and 500 KB total source text. Split or curate a large archive first.

# [launch] Autumn launch | milestone | open | Release after the recorded review.
Needs [[review|depends on]].
# [review] Design review | decision | active | Inspect the supplied design.
Uses [[checklist|uses]].
# [checklist] Review checklist | document | done | The supplied acceptance checklist.

Inspect relationship evidence separately from node evidence

Choose Import Markdown, import launch.md and inspect all three entities. Open the launch-to-review relationship and compare its path, line and exact excerpt with line 2 of your file. Then inspect review-to-checklist at line 4. Finding a matching line proves the excerpt exists there; it does not prove the relationship is factually correct or semantically supported.

Missing targets, self-links and links before a heading produce warnings and are omitted. Review those warnings rather than treating a partially imported graph as complete. Duplicate IDs, invalid states and inconsistent structured provenance reject an import without replacing the current project.

Test one known path and one direction-sensitive absence

Clear search and filters before reviewing the whole graph. A missing path means none exists in this recorded data under the selected direction setting; it does not prove a dependency is absent in the real project. When a relationship matters operationally, open each edge’s source and confirm its meaning with the owner.

Save editable work and review the complete export

Edit labels, summaries and lifecycle states, then use undo/redo to inspect the change. Save both Project JSON and a portable atlas, reopen the portable HTML and verify the edit and evidence remain. Entity and connection forms create a new source note at line 1; import original Markdown when retaining its original file line numbers matters. Browser changes do not rewrite your original notes.

Inspect the SVG, Mermaid, entities CSV and relationships CSV. Exports contain the complete project, even when the visible view is filtered. CSV neutralizes leading spreadsheet formula prefixes; JSON preserves literal authored values. Neither makes confidential source text safe to publish. Review all embedded sources before handing the files to another person.

Optionally build a repeatable local delivery

The browser is enough for the first result. If you need a repeatable file delivery, the optional Node.js 18+ CLI uses only the standard library and does not call a service. From the complete installed package, build the included fictional project with the command below. For your own project, replace the input with downloaded Project JSON. Choose a new output folder; an existing one is protected.

• Open the generated index.html and compare the map with project.json and both CSV files. Verify each file’s SHA-256 against delivery-manifest.json. A matching manifest verifies file integrity, not the truth of source notes.
• Use search, zoom or the accessible entity list for larger maps. Review the handoff at a narrow width. Preserve the approved source archive and unresolved contradictions; public hosting and source governance remain separate work.

Compare with a deliberately authored architecture system map

Turn reviewed project knowledge into an admin-console plan

node scripts/build.mjs --input examples/default.json --output ./my-atlas