A Hub That Can Explain Itself

Every intelligent knowledge system begins with a less glamorous moment: the return. You reopen a research thread, a software design, or a long agent conversation and can no longer tell why a decision was made, which source carried a claim, or whether a polished draft was ever reviewed. The work exists, but its trail has gone cold.

This is the story of building a way back. It follows an eight-stage return journey, but the hero is not an autonomous agent. It is the person who keeps the right to decide what the system means and what it may do. At each stage, you draft one small artifact. By the end, you have a set of candidates for prototyping a governed knowledge hub: a system intended to explain where its material came from, what state it is in, and what should happen next. The tutorial does not itself produce or validate a working system.

The examples draw on the Hearth & Code Hub and Core32 profile sources. They are patterns, not evidence that every part of that system is complete, active, or universally applicable.

1. The ordinary world: work that cannot find its way home

The starting problem is familiar to anyone doing doctoral research, information management, or agentic engineering. Papers, notes, prompts, design decisions, and generated drafts accumulate faster than their relationships can be remembered. Search can find a phrase, but it cannot recover the question that made the phrase matter.

The first move is not a folder tree. It is a research-question register: one compact record that turns a topic into a bounded question. This is the moment the builder realizes that a compelling idea is not yet a researchable question, and a researchable question is not yet a defensible claim.

Make: a question candidate with terms, boundary, evidence need, and a next human decision.

2. The call to adventure: give every source a trail

The next obstacle is source fog. A literature review becomes less trustworthy when summaries lose their relation to the paper, a conversation is mistaken for a citation, or an agent’s synthesis is silently promoted to evidence.

Create a source card for every material item. A card does not replace a source. It preserves enough context to make later comparison honest: identity, supplied scope, attributable claims, method, limitations, and relation to the question.

Make: one source card from an excerpt you have actually opened.

For doctoral work, this is the first threshold. You are no longer only collecting papers; you are preparing material that a future chapter can interrogate. In a software project, substitute requirements, user research, and technical specifications. These are analogous examples, not evidence that the same workflow has been evaluated in each setting.

3. The refusal: do not let a plausible answer become authority

Once a system can collect and summarize, it will tempt you to move too quickly. A generated answer can feel complete long before its source, owner, or permission is settled. A useful hub refuses this move: no fluent artifact becomes a decision simply because it is convenient.

An AGENTS.md-style root policy gives the refusal a stable form. It says who retains authority, which sources outrank summaries, which actions need a separate gate, and what happens when the system cannot close a boundary. The answer to an unknown is not improvisation. It is HOLD: preserve what is known, name the missing evidence, name the owner, and return one bounded question.

Make: a decision-and-return record, but only when the human has actually decided.

4. Meeting the map: give candidates a canonical home

The hero now needs a map, but a path is not authority by itself. Route artifacts by purpose and lifecycle. Sources live apart from candidates; receipts live apart from decisions; private authoring material stays distinct from public-safe projections. Local instructions can narrow rules for a work area, but cannot weaken root boundaries such as provenance, privacy, or human release.

Start with four surfaces, not a grand taxonomy:

knowledge-hub/
  AGENTS.md          # authority, source rules, non-effects, hold behavior
  sources/           # original material and source cards
  candidates/        # drafts, maps, and proposed decisions
  receipts/          # bounded checks and return records
  profiles/          # optional: one source per recurring transformation

Now that you have source cards, create a claim-and-evidence ledger.

Show one ledger claim, its sources, its limit, and its next check. That makes the method demoable without exposing an entire private corpus.

Fictional miniature: a validator summary [S1] says that 7 of 10 supplied records contained the required fields under one named predicate. A bounded ledger could return:

• Claim [C1] · evidence: “Seven of the ten records in [S1] contained the required fields under predicate P.”
• Limit: this says nothing about whether the field values are semantically correct, whether an agent followed its scope, or whether the system is useful.
• Next check: inspect the three records that failed P and confirm that P matches the intended requirement.
• State: candidate for review; the validator result is not acceptance.

The counts and records here are invented for teaching. No actual validator run or system outcome is claimed.

5. Meeting the mentors: specialize by transformation, not personality

The next temptation is to create a cast of impressive-sounding agents. Resist it. A specialized profile earns its place only when it owns a distinct, recurring transformation.

Historical Core32 profile candidates illustrate three distinct role boundaries. Eidos, the semantic-systems architect, turns concepts, terms, relations, and representation needs into a governed semantic system. Technographus, the skill-system architect, turns recurring capability evidence into a bounded skill system. Prosopographus, the profile architect, turns recurring role evidence into a modular profile source. Their candidate.11 Archetypes and candidate.16 profile YAML records retain those same transformation identifiers. Both snapshots remain source-only and review-required; this comparison does not show that a profile is accepted, installed, loaded, or useful in a task. The point is to inspect role boundaries, not to assume a fleet is better than a general assistant.

As an exercise, compare four possible roles: source analyst, software builder, reviewer, and coordinator. In a literature task, the source analyst might map supplied materials without claiming to author the review. In a software task, a builder might return a patch candidate and test result, while a reviewer returns findings; a person still decides whether to integrate them. These are role-design examples, not a recommendation to create four agents.

An ARCHETYPE.md-style document can render a role’s identity, purpose, inputs, outputs, boundaries, recovery, verification, and lifecycle. In candidate.16, the role’s YAML family owns those semantics and the readable Archetype is a projection. A SOUL.md-shaped file may be prepared as a host-specific runtime projection, but that label does not mean a host has loaded it. Candidate.16’s deployment notes leave host compatibility, installation, and runtime testing pending. Keep source, readable projection, and any host mapping distinct until each has its own review and release.

6. The ordeal: make disagreement and limitation visible

An intelligent knowledge system does not merely produce synthesis; it makes seams in a synthesis visible. The difficult work is often not finding a common theme but keeping disagreement, absence, and counterevidence from being edited out by momentum.

Use the ledger to make a small disagreement map. For a doctoral chapter, this may show two accounts using the same term differently. For knowledge engineering, it may show two consumers needing different schemas. Sometimes the honest output is a boundary and a question, not a unifying definition.

7. The return: report what was checked, and no more

A validator can establish that a schema parses, a required field exists, or a forbidden pattern is absent. It cannot establish semantic correctness, usefulness, acceptance, or publication readiness. Those are separate evidence layers.

This is also where runtime honesty matters. A well-written profile candidate is not evidence that a fleet is installed, selected, active, or effective. The profile examples in this tutorial are tied to a historical candidate snapshot; this review has not reconciled each example against later source revisions or a runtime. Any claim about what is presently installed or operating needs separate, current evidence.

A small constitution and one companion soul

Here are two deliberately small, tool-neutral starting artifacts. They borrow the useful shape of the Hub’s sixteen-part profile approach while omitting its private references, detailed type system, and runtime configuration. They are not permission slips. Tailor them to your people, sources, and legal or institutional constraints before use.

The companion SOUL.md is not a claim about a machine’s inner life. It is a runtime-facing behavior contract for one profile. Keep it smaller than the root charter and make it concrete enough to refuse work outside its scope.

8. The gift brought home: a system others can try

The final gift is a return loop:

1. Frame a question and record its boundary.
2. Make source cards from material you actually inspected.
3. Separate claims, inferences, proposals, and unknowns.
4. Give each candidate an owner, a review state, and a next gate.
5. Delegate only a bounded transformation.
6. Write a receipt that says what the check did and did not establish.
7. Let the human decide the next state.

Try the loop with one bounded research question or software task. A walkthrough can show how the proposed artifacts connect; it cannot by itself demonstrate that the system improves outcomes. To evaluate that claim, define a task, a simpler baseline, observable criteria, and human review before comparing results.

The portable lesson is modest: make every important artifact capable of pointing back to its source, forward to its next decision, and sideways to the boundary it must not cross. A hub that can do that can explain itself—and, more importantly, can help its human return.

Practitioner bridge: make the handoff auditable

For an agentic researcher, use the pattern on one evidence synthesis: bind each extracted claim to an opened source span, keep extraction separate from interpretation, and return contradictions plus a bounded reading queue. For an agentic engineer, apply it to a bug-fix task: bind the issue, relevant code and test, let an agent propose a patch, then report changed files and which tests actually ran. These are two applications of the same source-to-candidate-to-check interface, not evidence that the tutorial has been evaluated in either domain.

A useful review question is whether a second operator can reconstruct the decision from the returned artifacts without trusting the first agent’s summary. Measure that with a fixed task and a simpler baseline: source-link recovery, unsupported-claim count, human repair time, and correct identification of unrun checks. If the extra records do not improve one of those decisions, remove them.

AI assistance disclosure: AI assisted with source comparison, structure, drafting, and review preparation. The authorial direction, factual verification, and any publication decision remain Scott’s.