An Astro skill · import
Raw material in, stars out.
Point it at a folder and it comes back as a graph: a codebase, a docs tree, a pile of papers, turned into real notes and real wiki-links inside your vault. Not an HTML file sitting next to the repo that goes stale the day it's made. Astro's 3D sky is the visualization, and every node is a Markdown file you can open, edit and link the moment it exists.
Ships with Astro, MIT licensed. Plain Markdown with a YAML header: no install step, no runtime, no dependency.
/stardust <path>
extract a folder into the open vault
/stardust <path> --update
only what changed since the last run
/stardust <path> --deep
richer inferred edges, more passes
/stardust <path> --dry-run
report what it would write, write nothing
/stardust query "..."
walk the graph, answer with file:line
/stardust audit
re-verify links, orphans, dupes, dead edges
What becomes a node
One note per idea, not one note per file.
Files are containers; nodes are ideas. A unit that appears in exactly one file and is referenced nowhere else isn't a node, it's a line in its parent's note. Being ruthless here is the only thing that keeps the resulting sky readable instead of a mirror of your directory tree.
Code
A module, an exported class or function, a config surface, an entry point. Not tests, not generated output, not vendored code, not lockfiles.
Docs
One document, or one H2 section when the document is long enough that its sections are separate ideas. Not changelogs, not licenses.
Papers and notes
One paper, one claim, or one concept named at least twice across files. Boilerplate is skipped.
The audit trail
Every edge says where it came from. No tag, no edge.
An extracted graph is only worth something if you can tell what was read and what was guessed. Each link carries its provenance in the note, so the difference survives past the run that made it.
EXTRACTED
Read straight out of the source: an import, a call, an explicit citation. The evidence is named on the edge itself, and it is never upgraded to from a guess without re-reading the file.
INFERRED
A conclusion, with the reasoning stated in one clause. Two modules mutate the same Redis key; two names turn out to be the same concept. Real, but reasoned rather than read.
AMBIGUOUS
Plausible and unconfirmed. These are listed in full in the audit note, because they are the ones a human should look at first.
Two notes land beside the import. A graph report in plain language: clusters, hubs, the cross-cluster surprises, what to read first. And a graph audit, the honest one: tag counts, every ambiguous edge with its reasoning, and the files that were skipped and why. A cap or a dropped directory is named there, never truncated silently.
Clusters and hubs
The structure your folders don't show.
Clusters are found by edge density, not by directory, which is the entire point: a set of notes that link to each other far more than to the rest of the graph, named for what it does rather than “Cluster 3”. A hub is a node in the top few percent by degree, marked in its own body with its connection count. Hubs are where a newcomer should start reading and where a refactor will hurt most, and the report says which. Cross-cluster edges lead the report, because those are the ones reading the files in order would never have shown you.
Then stop grepping
An answer is a path through the graph, with citations.
Once the graph exists, a question is answered by walking it: searching for entry points, reading the topology, stepping outward note by note. The answer comes back as an explicit path, A → B → C, carrying the file:line of every note it crossed. An answer with no path and no citation is a guess, and it says so instead of dressing it up.
When it refuses
Not running is often the right call.
- The open vault is about a different subject than the folder. It says which vault is open and stops rather than cross-posting.
- The folder is under about ten files. A graph of eight nodes is a list: read them.
- You asked one question about a codebase. Building a graph to answer it costs more than the answer is worth.
- Before the first write on a real import, it states the vault, the path and the estimated note count and waits for a yes. Hundreds of notes are not a silent side effect.
- A note you have since edited by hand is never overwritten by an update. If its source changed it gets a review callout appended instead.
Written up, not benchmarked
No numbers here either, and no invented ones.
The comparison that would matter, graph-walking against plain search on the same questions, needs a task suite that doesn't exist yet. So this gets the same reporting skeleton with a description in place of a result: the pipeline, the audit trail that makes its output checkable, and every place it is judgement rather than measurement.