Skip to content

docs: vocabulary design record (M19) #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jgrodziski merged 1 commit into from
Nov 5, 2026
Merged

docs: vocabulary design record (M19) #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
9 changes: 9 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,14 @@ On `serve`'s Vocabulary tab, the cloud and its table follow the package or
class selected in Navigate, and clicking a word lists the names that carry it,
each one click from its node.

Once `explain` has run, each explained entity's record also carries the
words of its names with the sense and the concern the model gave each one in
that entity, and every module reconciles its types' senses into a glossary:
`codegraph insights --word order` lists every entity that defines the word,
`--polysemy` the words whose senses disagree, and `codegraph vocabulary
--drift-insights` sets the rules' classes against the model's judgements.
The tab shows these under a clicked word as inferences, never as facts.

### Mine the history

```bash
Expand Down Expand Up @@ -430,6 +438,7 @@ so a model file has one direction of truth. The full reference is
- [`docs/distribution.md`](docs/distribution.md) — the Homebrew tap, what a tagged release produces, what is signed and how
- [`docs/navigator.md`](docs/navigator.md) — the navigator's design
- [`docs/insights.md`](docs/insights.md) — the explanation walk's design
- [`docs/vocabulary.md`](docs/vocabulary.md) — the vocabulary's design: the lexicons, the split, the classes and weights, `vocabulary.json`, the cloud, the words a model defines and the glossary readers
- [`PLAN.md`](PLAN.md) — milestones, decisions and their rationale
- [`CLAUDE.md`](CLAUDE.md) — architecture boundaries and the metamodel invariants

Expand Down
2 changes: 1 addition & 1 deletion docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,7 @@ scope, weights, view and technical list, the same bytes on every run.
drawn with `--top 80`. One word across the city is the `city` metric
`vocabulary:<word>` (above):
[`vocabulary-city-broadleaf.png`](vocabulary-city-broadleaf.png) is
BroadleafCommerce's city with `--height vocabulary:order`.
BroadleafCommerce's city with `--height vocabulary:order`. Design record: [vocabulary.md](vocabulary.md).

### `domain-facts`
One JSON artifact (`codegraph.domainFacts/1`) with one dossier per corpus
Expand Down
Loading
Loading