From repository to content graph

Before you connect anything

Three things worth deciding first, because they shape everything that follows.

• Which repository — one with content in structured files gives the most useful first result
• Which paths — you authorize specific repositories, and within them discovery can be pointed at content directories
• Read-only or not — read-only is the default and is enough for the inventory, search and health

1. Connect

• Install the GitHub App on the organization or account
• Authorize repositories individually — there is deliberately no all-repositories shortcut
• Confirm the default branch discovery should read from

2. Discover

Discovery parses supported files and proposes the content model it found. Nothing is bound yet.

• Supported formats: TypeScript and JavaScript exports, JSON, YAML, Markdown and MDX
• TypeScript types and interfaces are used as the proposed schema where they exist
• Repeated object shapes are inferred where no type exists
• Files that could not be parsed are listed as skipped, with the reason, rather than omitted silently

3. Review the model

This is the step that needs you, and it is the one that determines whether everything afterwards is correct.

• Confirm which exports are content and which are configuration — a routing table is not content
• Check the source bindings on a sample of assets against the actual files
• Decide which structures should eventually be writable, once write-back exists

4. Build the graph

• Assets are created with stable identifiers and their bindings
• Relationships are inferred where the structure implies them, and asserted where you add them
• Git history is imported as provenance evidence — committed by, introduced in commit
• Search and semantic indexes are built, scoped to your tenant

5. Start asking

The first useful hour is usually spent on questions nobody could previously answer.

• Where do we mention this capability?
• Which pages describe the same thing differently?
• Which content has no determinable author?
• Which product capabilities have no dedicated page?

What discovery will not do for you

Stated plainly, because finding out later is worse.

• Extract copy that is hard-coded inside JSX — it has no stable binding, so it is surfaced where detected but stays read-only until a developer moves it into a content module
• Discover content generated at request time from an external API — it is not in the repository
• Decide which exported objects are content and which are configuration — a routing table is not content, and that judgement is yours
• Write to a repository on the strength of a read connection — write access is always a separate, explicit grant