Doc Doctor · Josué Guevara

Problem

Editorial review creates work that is easy to lose: a missing source, a section that needs expansion, a question that blocks publication, a contradiction that must be fixed. Comments record those gaps as prose. Doc Doctor gives each gap a durable type, anchor, state, and workflow.

Origin

Doc Doctor grew from recurring problems in documentation, governance, review, and knowledge-management work: unsupported claims, unresolved questions, incomplete explanations, contradictions, and material waiting for review. The project turns those gaps into typed, anchored objects with state and operations shared by the Obsidian interface, developer tools, and agents.

Position

The project separates deterministic editorial state from assisted interpretation. Stub types and document properties can be inspected directly. AI can propose or help resolve work. The gap, state, and workflow remain explicit.

System

StubsTyped editorial gaps including citation, expand, question, and fix, synchronized between inline anchors and frontmatter.
SidebarNavigation, filtering, sorting, and stub operations in the document workspace.
FederationA capability-scoped public API and dedicated Amnesia integration exchange reading state, highlights, stubs, resolutions, health state, and events across plugin boundaries.
AssistanceSchema-driven prompts, multi-provider LLM support, stub suggestions, document analysis, and constrained remediation workflows.
GroundingCorpus search, reference lookup, claim grounding, bibliography enrichment, and formatted citation services.
HistoryGit-backed time-travel views and lifecycle/milestone operations where dependencies are available.
Agent surfaceMCP surfaces for document parsing, validation, analysis, and stub workflows; Rust components continue to evolve.

AmnesiaBooks · highlights · reading state · source locators

Doc DoctorStubs · document state · AI · grounding · citations · MCP

Implemented federation boundary: each system keeps its own domain while exchanging scoped state and operations.

Implemented · Amnesia → Doc Doctor Books, highlights, reading state, and knowledge-gap annotations can become structured Doc Doctor inputs. Eligible highlights synchronize to typed stubs with deduplication and conflict handling.

Implemented · Doc Doctor → Amnesia Stub resolutions and document-health state can return through the bridge and update the reading-side workflow.

Planned: Make Amnesia’s source-addressed passages first-class retrieval material when Doc Doctor searches for evidence or resolves citation gaps.

Demonstration

A link/citation stub is resolved from the same Obsidian document and sidebar surface.

Doc Doctor — citation resolution1/4 · Citation gap

Authentication guide

GuidesAuthentication guide

Properties

form: developing
audience: public
owner: developer-experience
release: 2026.09
refinement: 0.72
stubs: link · 2expand · 2question · 1

Authenticate API requests

Clients authenticate with bearer tokens issued from a workspace. Keep tokens outside source control and inject them through the runtime environment.

Create credentials

Workspace owners and administrators can create API credentials from Settings → Developer. Clarify which custom roles inherit this permission.^stub-role-scope

Send a request

Pass the token in the Authorization header on every request. Add browser-client guidance and CORS example.^stub-browser-example

curl https://api.example.test/v1/items \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Retry transient failures

Retry failed requests for up to 30 seconds using capped exponential backoff.^stub-retry-policyCITATION NEEDED

Retry failed requests using capped exponential backoff with a maximum retry window of 30 seconds.^{[^1]}

[^1]: Retry policy benchmark fixture, validation run 04.

The service returns 429 when a workspace exceeds its burst allowance. Verify whether Retry-After is emitted on every 429 response.^stub-retry-after

Rotate tokens

Rotation can overlap old and new credentials during migration. What is the supported grace period for overlapping credentials?^stub-rotation-window

Doc Doctor · stubsMarkdown

The document text is synthetic. The stub list, controls, anchor treatment, and workflow correspond to the current Doc Doctor implementation.

Decisions

Make editorial gaps first-class typed objects. A missing source, expansion, question, or fix carries a type, anchor, state, and lifecycle that can be queried and changed directly.
Separate stored document properties from calculated state and operational rules. J-Editorial’s layers keep durable facts distinct from context-dependent dimensions and from the rules that act on them.
Keep the Rust domain core independent of infrastructure. The hexagonal core defines entities, calculations, errors, and ports; YAML, filesystem, MCP, WASM, CLI, and other interfaces sit behind adapters.
Keep calculations deterministic and put model assistance outside the domain boundary. Health, usefulness, validation, and state transitions remain testable without an LLM; model providers assist through constrained orchestration surfaces.
Use format-agnostic parser and repository ports. The domain operates on document concepts; Markdown/YAML storage remains an adapter concern.
Expose cross-plugin capabilities through scoped APIs. Document operations, stubs, events, recommendations, and Amnesia integration sit behind explicit capability grants so adjacent plugins can reuse shared domain operations through a stable boundary.
Use Obsidian as the primary human work surface and expose the same operations to tools. The plugin, MCP server, CLI, and WASM adapters enter shared domain operations and rules.
Keep document history and provenance inspectable. Git-backed history and explicit lifecycle records expose how a document changed and which state transitions occurred.

Further inspection

Open the product demo Inspect the federated reading system Read the framework behind the editorial model