Curation And Search

This document defines the permanent functional scope owned by the consolidated-docs repository within the document system.

Repository Responsibility

consolidated-docs manages documentation curation and search scope for the docs hub. This includes:

• curation admission decisions
• rules for what content belongs in the consolidated document system
• organization and surfacing of admitted documentation
• global search behavior for consolidated documentation
• global search indexing scope, exclusions, and related verification notes

Curation

This repository is the durable home for documentation describing how content is admitted into the consolidated docs hub.

In consolidated-docs, curation is not an abstract concept. It is the managed inclusion state of child documentation repositories in the hub manifest:

• curation/curated-doc-sites.yml

A repository is curated when it is present in that manifest. A repository is removed from curation when it is removed from that manifest.

The managed add/remove workflow is implemented by:

• scripts/curation_inventory.py

That tool is the operative curation interface. It scans workspace candidates, assesses each repo, shows inventory rows, and supports explicit actions:

• include <id-list>
• remove <id-list>
• done

This means curation in this repo specifically includes:

• deciding whether a repo should be included in curated-doc-sites.yml
• deciding whether an already curated repo should remain included
• assigning its displayed title, category, and ordering in the manifest
• retaining or updating its recorded quality status and template version

Current implemented quality gate

The curation inventory tool performs a lightweight admission check before or during inclusion review. The implemented checks currently include:

• mkdocs.yml parses
• docs/ exists
• docs/index.md exists
• hooks/update_date.py exists
• hooks/build_semantic_registry.py exists
• .docs-template-info.json exists
• template package is mkdocs-oves-template
• global search bridge version matches the required version
• for already curated repos, hub integration flags remain enabled

The tool reports a repo status of pass, warn, or fail, and persists curated membership through the manifest. Curated entries may still carry warning or failure status; curation membership and quality status are related but not identical concepts.

Generated hub behavior

The hub uses the curated manifest as its source of truth. The documented generator flow reads the curated manifest and then regenerates:

• mkdocs.yml navigation
• docs/index.md

Therefore, curation directly controls what appears in the consolidated docs hub.

Search implication

Because the global document index is curated, inclusion in hub curation is also the practical gate for search-scope participation in the consolidated docs system. When curated child content changes must be reflected in the hub search index, the hub update and index rebuild workflow must be run explicitly.

Search And Indexing

This repository is also the durable home for global search and search-index documentation for the docs hub.

Search-related documentation in this repo should answer:

• what content is indexed
• what content is excluded from indexing
• how global search is expected to behave across curated documentation
• what known issues, mitigations, and validation steps exist for the search index

Static global index model

The consolidated global search index is a locally built, committed, static artifact.

That statement is intentional and mandatory:

• the hub search index is built by content developers in the full workspace
• the resulting search artifact is committed into consolidated-docs
• cloud deployment serves that committed static artifact
• cloud deployment does not rebuild the curated cross-repo search corpus
• cloud deployment does not discover sibling repos
• cloud deployment does not perform cross-repo search harvesting

Therefore the hub's deploy-time responsibility is limited to:

• serving the committed global search artifact
• resolving target links for the active environment origin

The only environment-specific variation between local and cloud for global search hits is the target URL origin handling. The indexed content itself is already pre-built and static by the time the hub is deployed.

If curated child content changes and those changes must be searchable from the hub, that is a local content-promotion step, not a cloud deployment step.

Implemented Curation And Search Tools

The current durable curation and search workflow is implemented through these artifacts:

• curation/curated-doc-sites.yml
• the curated membership manifest for the hub
• scripts/curation_inventory.py
• the add/remove review tool for curated membership
• ../generate-consolidated-docs.py
• the hub generator that rebuilds navigation and landing content from the curated manifest
• mkdocs-oves-update-global-index
• the child-repo promotion command that refreshes hub content and rebuilds the committed curated global search index locally before deployment
• scripts/build_docs_search_registry.py
• the local search-registry build step referenced by the repo README

Together, these define the actual curation workflow rather than a merely conceptual one.

Deploy-Time Rule

For consolidated-docs, the deploy-time rule is explicit:

• the hub must be independently buildable
• the deployed hub must not depend on sibling repos being present in cloud CI
• the deployed hub must not rebuild the curated cross-repo search corpus in cloud CI
• the deployed hub must serve the committed static curated index that was built locally by content developers

Any implementation that assumes cloud-side access to sibling documentation repos violates the document-system operating model.

Current Inventory Baseline

The current assessed curation baseline should be persisted in repo docs when an inventory pass materially refreshes understanding. The current snapshot is recorded in:

• the curation inventory status page

That inventory page is the durable place to capture:

• current curated count
• current warning/failure posture
• known candidate repos outside curation
• known limitations in the inventory tool itself

Known Tool Limitation

The current curation inventory tool assumes a single-language child repo layout with docs/index.md. That creates a false failure for repos that use the multilingual template layout, such as mkdocs-template, where the entry pages live under language folders such as docs/index.md.

Until the tool is made template-aware, inventory output for multilingual repos must be interpreted with this limitation in mind.

Persistence Rule

This repo exists partly to prevent repeated re-contexting. Therefore the following rule applies to curation, search, and hub-management work in consolidated-docs:

• whenever a new script, tool, workflow, verification step, or operating rule is created for hub curation or search, it must be evaluated for persistence
• the operator must be prompted whether it should be persisted
• if the answer is yes, the durable description belongs in this repo

Persistence normally means updating one or more of:

• this system document
• the repo README
• the curated manifest or related config
• workflow-specific documentation under docs/

If the persisted change affects rendered docs content, the document-system artifacts must be refreshed so the change is discoverable. For this repo that means:

• rebuild the hub content
• rebuild the relevant search index artifacts
• ensure the updated content is part of the document system and searchable

This is a mandatory operating rule, not an optional cleanup task.

Boundary With mkdocs-template

Do not store template-standard, template-adoption, repo artefacts package, or template conformance tooling documentation here unless it is specifically about how those things affect consolidated-docs curation or search behavior.

Those template-related concerns belong in mkdocs-template.

Document System Requirement

This page is permanent documentation, not temporary session context. It belongs in the docs tree so it is built, indexed, and searchable as part of the document system.