# Phase 166.1: Contentful Source Registration Default - Context

**Gathered:** 2026-04-13
**Status:** Ready for planning

<domain>
## Phase Boundary

This phase makes the arXiv registration path contentful-by-default after the
new Phase `166` handoff. It covers direct registration, discovery-to-
registration forwarding, docs, and one bounded fresh-topic proof of
`bootstrap -> handoff -> registration`. It does not expand beyond arXiv, does
not add automatic source execution from the runtime queue, and does not reopen
the already-finished Phase `166` handoff surface except where the registration
default must stay aligned with it.

</domain>

<decisions>
## Implementation Decisions

### Default registration behavior
- **D-01:** `register_arxiv_source.py` should attempt source download and
  extraction by default. The normal direct registration path should become
  contentful without requiring `--download-source`.
- **D-02:** Add an explicit `--metadata-only` opt-out for lightweight
  registration. This opt-out should cleanly disable source download while
  preserving the rest of the registration path.
- **D-03:** Keep the existing graceful fallback rule: if source bundle download
  or extraction fails, the paper still registers, the failure stays visible in
  `snapshot.md`, and the runtime must not pretend content was acquired.

### CLI compatibility and forwarding
- **D-04:** Preserve `--download-source` as a compatibility alias or explicit
  positive flag so older command examples and wrappers do not break abruptly.
- **D-05:** `discover_and_register.py` must follow the same default as direct
  registration; otherwise the new Phase `166` primary handoff would still drop
  users into metadata-only behavior. It should also surface the same
  `--metadata-only` opt-out.
- **D-06:** The intake compatibility wrapper
  `research/knowledge-hub/intake/scripts/register_arxiv_source.py` should keep
  working without special-case divergence; behavior should remain routed through
  the same Layer 0 helper.

### Docs and operator expectations
- **D-07:** Operator docs should treat contentful registration as the normal
  path. Examples in `ARXIV_FIRST_SOURCE_INTAKE.md` should no longer require
  `--download-source` to get content, and should document `--metadata-only` as
  the lightweight override.
- **D-08:** The phase should keep operator language honest: "contentful by
  default" means "attempt source acquisition by default with explicit fallback
  reporting," not "guaranteed TeX success."

### Verification boundary
- **D-09:** Phase `166.1` should add targeted unit / CLI regression coverage for
  the new default semantics and the `--metadata-only` opt-out.
- **D-10:** The phase must also leave one bounded fresh-topic proof of
  `bootstrap -> concrete handoff -> registration` on the real repository kernel
  root, because `REQ-VERIFY-01` stays open until that path is durably proven.

### the agent's Discretion
- exact parser shape for compatibility between `--download-source` and
  `--metadata-only`
- whether compatibility output calls the positive default flag "deprecated" or
  simply keeps it as a harmless synonym
- exact proof artifact naming for the fresh-topic registration evidence bundle

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Milestone scope and requirement routing
- `.planning/ROADMAP.md` — Phase `166.1` goal, dependency on Phase `166`, and
  fresh-topic proof requirement
- `.planning/REQUIREMENTS.md` — `REQ-L0HAND-03` and `REQ-VERIFY-01`
- `.planning/BACKLOG.md` — item `999.71` is the original registration-default
  gap promoted into this phase

### Prior phase outputs that constrain this work
- `.planning/phases/166-public-front-door-l0-source-handoff/166-CONTEXT.md` —
  Phase `166` locked the query-first handoff and the honesty boundary this
  phase must preserve
- `.planning/phases/166-public-front-door-l0-source-handoff/166-01-SUMMARY.md`
  — confirms the current handoff now points at discovery first, so registration
  defaults must stay aligned with that path
- `.planning/phases/166-public-front-door-l0-source-handoff/166-VERIFICATION.md`
  — confirms the completed cross-surface handoff and the remaining open proof
  lane

### Source registration and operator docs
- `research/knowledge-hub/source-layer/scripts/register_arxiv_source.py` —
  primary registration helper whose default behavior changes in this phase
- `research/knowledge-hub/source-layer/scripts/discover_and_register.py` —
  query-first bridge that must inherit the same default semantics
- `research/knowledge-hub/intake/scripts/register_arxiv_source.py` —
  compatibility wrapper that must keep matching the Layer 0 helper
- `research/knowledge-hub/intake/ARXIV_FIRST_SOURCE_INTAKE.md` — operator doc
  that currently still teaches `--download-source`
- `research/knowledge-hub/L0_SOURCE_LAYER.md` — documented Layer 0 policy and
  current arXiv-first acquisition semantics
- `research/knowledge-hub/README.md` — top-level operator/docs references for
  discovery and registration

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `research/knowledge-hub/source-layer/scripts/register_arxiv_source.py`:
  currently exposes `download_source: bool = False`, a `--download-source`
  CLI flag, and already has the correct graceful fallback behavior when bundle
  download or extraction fails.
- `research/knowledge-hub/source-layer/scripts/discover_and_register.py`:
  currently forwards an explicit `download_source` boolean into
  `register_arxiv_source()`, so it will need to change together with the direct
  registration path.
- `research/knowledge-hub/intake/scripts/register_arxiv_source.py`: pure
  compatibility wrapper; no behavior should fork here.
- `research/knowledge-hub/tests/test_source_discovery_contracts.py`: already
  exercises direct registration and discovery→registration integration, making
  it the main regression surface for the new default behavior.

### Established Patterns
- Registration already distinguishes `download_status` and `extraction_status`
  while preserving successful metadata registration. This phase should reuse
  that durability pattern rather than inventing a new content state.
- Discovery and direct registration are intentionally thin wrappers over the
  same Layer 0 truth path, so defaults should stay aligned across both entry
  routes.
- Operator docs prefer explicit command forms. This phase should keep examples
  concrete and update them rather than adding prose-only notes about defaults.

### Integration Points
- `research/knowledge-hub/source-layer/scripts/register_arxiv_source.py` for
  function defaults, parser flags, and JSON output surface
- `research/knowledge-hub/source-layer/scripts/discover_and_register.py` for
  forwarded defaults and query-first CLI parity
- `research/knowledge-hub/tests/test_source_discovery_contracts.py` for direct
  and discovery-integrated regression coverage
- `research/knowledge-hub/intake/ARXIV_FIRST_SOURCE_INTAKE.md`,
  `research/knowledge-hub/L0_SOURCE_LAYER.md`, and `research/knowledge-hub/README.md`
  for doc parity

</code_context>

<specifics>
## Specific Ideas

- Preferred operator-facing default story: "If you follow the handoff and run
  `register_arxiv_source.py`, AITP now attempts to acquire source content
  automatically; use `--metadata-only` only when you explicitly want the
  lightweight path."
- Because Phase `166` made `discover_and_register.py` the primary handoff for
  topic-query cases, `discover_and_register.py` should behave like a contentful
  registration bridge by default too.

</specifics>

<deferred>
## Deferred Ideas

- provider expansion beyond arXiv-backed content acquisition
- automatic discovery/registration directly from the runtime queue
- broader retry, caching, or download-manager redesign beyond the existing
  graceful fallback surface

</deferred>

---

*Phase: 166.1-contentful-source-registration-default*
*Context gathered: 2026-04-13*
