Repository navigation
Make the tool import existing ADR docs in a repository #504
Description
What problem does this solve?
Most repositories contain existing ADR documentation that might be of interest codebase-memory.
Proposed solution
It would be nice if the initial project onboarding would import those docs as well.
Alternatives considered
No response
Confirmations
- I searched existing issues and this is not a duplicate.
Activity
DeusData commentedon Jun 18, 2026
Thanks so much for this, @rikbosch 🙏 It fits naturally with the existing
manage_adrtool, which already stores ADRs in the graph; we just don't bootstrap from what's already on disk yet. For a first cut we'd detect a conventional ADR location (docs/adr/,adr/, or MADR styleNNNN_*.mdfilenames) and import them soget_architectureandmanage_adrsurface them.Two quick questions: (1) auto detect, or a config key like
adr_path? (2) one time import on first index, or keep them in sync via the watcher? If you have a preferred ADR tool (MADR or log4brains), let us know which to target first. PRs very welcome!rikbosch commentedon Jun 22, 2026
Maybe a combination? Scavenge most user paths line docs/adr or other known paths like **/adr/*.md?
I'd keep them in sync just like the rest of the code. The adr documents should be immutable, but they can be superseded by newer adr documents.
DeusData commentedon Jun 23, 2026
This overlaps heavily with #507, which proposes the broader MADR multi-record support — including importing existing ADR records already present in a repo. Marking this
duplicateand consolidating the discussion under #507 so the "import existing docs" piece is tracked as part of that work. Leaving this open for visibility for now. Thanks for raising it.DeusData commentedon Jul 1, 2026
Re-checked this under the stricter duplicate rule we are using now: this is related to #507, but it is not a 100% duplicate.
#507 is the broader Markdown/MADR support track. This issue is specifically about importing existing ADR documents during onboarding/indexing, so I am keeping it open as a distinct acceptance criterion and removing the
duplicatelabel. We should still implement it in coordination with #507.DeusData commentedon Oct 25, 2026
Thank you for clarifying that existing ADR files should stay synchronized and retain supersession history. Importing repository ADRs remains a distinct acceptance criterion coordinated with #507, rather than a duplicate to close. No additional reporter detail is needed to retain that scope. Sorry for the delay—this is waiting on maintainer follow-up, and I’ll follow up soon.
datadevdavid commentedon Nov 12, 2026
Data point from v0.12.1: the indexer already finds a repo's ADR files, but the ADR surfaces don't show them.
Setup: a repo with 43 ADRs in
docs/decisions/(NNNN-title.md, plus amendments namedNNNNa-title.md), alongside aREADME.mdand aTEMPLATE.md.What the index has: all 43 files became
ADRnodes, each with itsSectionchildren andSUPERSEDESedges between them.README.mdandTEMPLATE.mdwere correctly skipped. So detection already works, even for a non-conventional path.What the ADR surfaces show: nothing. The graph UI's ADR workspace (
?workspace=adr,GET /api/adr→{"has_adr":false}) andmanage_adr(outline:headings: 0) read onlyproject_summaries. That table is empty until someone writes the single summary document by hand. Users with a fulldocs/decisions/folder open the ADR tab and see "no record yet".Suggested first cut for this issue: list the indexed
ADRnodes (name, title, file, supersedes/superseded-by) in the ADR workspace and in themanage_adroutline, next to the hand-written summary or in place of it when the summary is empty. The nodes are already kept in sync by the watcher, which covers the "keep them in sync" point above without a separate import step.Two related gaps that make the existing nodes hard to find:
mdr_adr_idinsrc/pipeline/doc_links_md.cbuilds the name asADR-%u, so0032-….mdbecomesADR-32, while documents and code cite it asADR-0032. As a result,search_graphwithname_pattern: "ADR-0032"returns nothing. Amendments like0006a-….mdfail the digits-only parse and fall back to the file stem, so they have noADR-…name at all.ADR-NNNNmentions in code comments aren't linked. In the same repo, about 300 source files citeADR-0NNNin comments. None of these becomes aMENTIONSedge to theADRnode, and none appears indoc_link_unresolvedeither. That leaves no graph path from code to the decision behind it.