Consolidate contributor editorial guidance

CONTRIBUTING.md

@@ -43,6 +43,16 @@ Each independently versioned module contains:
 7. Mark rapidly changing information with a verification date.
 8. Keep entries concise enough to scan but detailed enough to teach.
 
+## Contribution paths and editorial guidance
+
+Use the narrowest contribution path that fits the change. Improvements to existing knowledge are as valuable as new modules when they strengthen accuracy, depth, evidence, or discovery.
+
+- [Contribution paths](docs/CONTRIBUTION_PATHS.md) — corrections, source upgrades, examples, architecture, relationships, deepening, and discovery work.
+- [Source quality guidance](docs/SOURCE_QUALITY.md) — claim-level evidence hierarchy, freshness, security-sensitive sourcing, and comparison discipline.
+- [Kind-specific editorial checklists](docs/KIND_EDITORIAL_CHECKLISTS.md) — review prompts for tools, languages, frameworks, infrastructure, databases, security, protocols, AI/ML, concepts, and open-source ecosystems.
+- [Relationship suggestions and validation](docs/RELATIONSHIP_SUGGESTIONS.md) — precise graph-edge selection, directionality, evidence, and anti-inflation rules.
+- [Generated index/search preview](docs/GENERATED_PREVIEW.md) — deterministic local preview and representative search checks before review.
+
 ## Local checks
 
 Before opening a pull request that changes core tooling or catalogs, run:

docs/CONTRIBUTION_PATHS.md

@@ -0,0 +1,121 @@
+# Contribution paths
+
+OpenDevIndex contributions do not need to add a new technology module. Small, well-scoped improvements to existing knowledge are often more valuable because they strengthen trust, depth, discovery, or navigation without expanding the catalog unnecessarily.
+
+Use the narrowest contribution path that matches the change you can support with evidence.
+
+## Correct a factual weakness
+
+Use this path when an existing statement is inaccurate, misleading, obsolete, or too absolute.
+
+Expected change:
+
+- identify the exact claim that needs correction;
+- replace it with the narrowest accurate wording;
+- add or update an authoritative source that supports the corrected claim;
+- update verification metadata when the corrected fact is time-sensitive;
+- avoid unrelated editorial rewrites in the same pull request.
+
+A correction should improve factual reliability without silently changing unrelated architecture, taxonomy, maturity, or graph data.
+
+## Improve sources or provenance
+
+Use this path when the module is directionally correct but its evidence is weak, stale, secondary when a primary source exists, or broader than the claim it supports.
+
+Expected change:
+
+- prefer official specifications, documentation, release notes, design documents, or project-maintained references;
+- match each replacement source to the claim it actually proves;
+- preserve useful secondary sources when they add independent context rather than merely duplicating a primary source;
+- do not increase confidence or maturity only because more URLs were added.
+
+See `docs/SOURCE_QUALITY.md` for the detailed source-quality workflow.
+
+## Add a practical example or workflow
+
+Use this path when a module explains what a technology is but does not yet help a reader perform a representative task.
+
+Good additions include:
+
+- a minimal command sequence;
+- a small API or configuration example;
+- a troubleshooting or recovery workflow;
+- a concrete lifecycle walkthrough;
+- an example that exposes an important boundary or failure mode.
+
+Examples should teach the concept without becoming a substitute for upstream documentation. Prefer small, stable examples over large copied configurations.
+
+## Add or clarify architecture
+
+Use this path when the module names components but does not explain ownership, data flow, control flow, process boundaries, protocol boundaries, or where state actually lives.
+
+Expected change:
+
+- identify the reader question the architecture explanation answers;
+- distinguish components that own state from components that only observe or transform it;
+- separate control-plane and data-plane behavior where relevant;
+- call out important external dependencies and failure boundaries;
+- support non-obvious architecture claims with authoritative evidence.
+
+Avoid decorative diagrams or terminology lists that do not improve the mental model.
+
+## Add a graph relationship
+
+Use this path when an existing module is missing a meaningful connection that helps readers navigate architecture, dependencies, compatibility, history, or alternatives.
+
+Before editing graph data:
+
+1. start from a concrete reader or architecture question;
+2. choose the narrowest supported relationship type;
+3. verify directionality;
+4. ensure the target module actually exists;
+5. add evidence for non-obvious claims;
+6. run the relationship validator and generated-index checks.
+
+Do not add links only to increase graph density. See `docs/RELATIONSHIP_SUGGESTIONS.md` for the complete workflow.
+
+## Deepen an existing module
+
+Use this path when an overview is correct but not yet useful enough as a guide or deep dive.
+
+Prefer depth that adds one or more of the following:
+
+- a stronger mental model;
+- architecture or internals;
+- realistic workflows;
+- recovery and failure diagnosis;
+- performance or reliability trade-offs;
+- security or privacy boundaries;
+- meaningful alternatives;
+- a beginner-to-advanced learning path.
+
+Do not raise maturity mechanically. Use `docs/MODULE_DEEPENING_CHECKLIST.md` and the kind-specific editorial checklist before claiming a maturity change.
+
+## Improve discovery without changing knowledge claims
+
+Use this path for search metadata, taxonomy fit, comparison discovery, generated navigation, or other findability improvements that do not alter substantive technical claims.
+
+Expected change:
+
+- explain which discovery problem is being solved;
+- keep ranking or taxonomy changes narrow and deterministic;
+- preview generated catalog/search artifacts;
+- test representative queries or navigation paths;
+- verify that existing stable module addresses do not regress.
+
+See `docs/GENERATED_PREVIEW.md` before opening the pull request.
+
+## Keep pull requests narrow
+
+A contribution is easier to review when it has one primary purpose. If a correction uncovers a separate architecture rewrite or new comparison opportunity, prefer a follow-up pull request unless the changes are inseparable.
+
+For every path:
+
+- preserve stable module identifiers;
+- do not copy upstream manuals wholesale;
+- do not treat generated text as an authoritative source;
+- do not make unrelated schema, maturity, or graph changes;
+- run the relevant local validators before requesting review;
+- describe what was intentionally left unchanged.
+
+The goal is not to maximize changed lines. The goal is to leave one useful part of the map more accurate, teachable, connected, or discoverable than it was before.

docs/GENERATED_PREVIEW.md

@@ -0,0 +1,65 @@
+# Preview generated index and search changes
+
+OpenDevIndex keeps generated discovery artifacts deterministic so contributors can review the public effect of a catalog or metadata change before opening a pull request.
+
+## Build the preview
+
+From the repository root:
+
+```bash
+python -m pip install -r requirements-ci.txt
+python scripts/validate_catalog.py catalog/v0.1.yaml
+python scripts/build_index.py --catalog-dir catalog --output-dir dist/index
+```
+
+The generated preview lives under `dist/index/`:
+
+- `catalog.json` — API-friendly public catalog records and aggregate counts.
+- `search.json` — searchable records and normalized search text.
+- `catalog.md` — human-readable browse/index rendering.
+
+If your change also affects comparison metadata, first generate the comparison index using the repository's comparison tooling and pass that file to `build_index.py` with `--comparison-index` so backlinks are included in the preview.
+
+## Review the diff
+
+Keep generated review separate from hand-authored source changes. A useful local sequence is:
+
+```bash
+git status --short
+git diff -- catalog quality comparisons docs
+python scripts/build_index.py --catalog-dir catalog --output-dir dist/index
+git diff --no-index /dev/null dist/index/catalog.md || true
+```
+
+For JSON artifacts, prefer structural inspection over reading minified fragments. Useful checks include:
+
+```bash
+python -m json.tool dist/index/catalog.json >/tmp/opendevindex-catalog.pretty.json
+python -m json.tool dist/index/search.json >/tmp/opendevindex-search.pretty.json
+```
+
+Then inspect the records affected by your module, kind, domain, coverage area, maturity level, or comparison.
+
+## Search the preview
+
+Run representative queries against the generated search index:
+
+```bash
+python scripts/search_index.py "your query" --index dist/index/search.json
+```
+
+Use at least one query that should find the changed module and, when relevant, one nearby query that should not become noisier or misleading because of the change.
+
+## What to verify
+
+Before opening a pull request, confirm that:
+
+- module counts and facet counts changed only when expected;
+- the changed module appears under the intended kind/domain/coverage facets;
+- maturity metadata is reflected correctly;
+- comparison backlinks appear only for validated curated comparisons;
+- search text gains only relevant terms and does not introduce accidental keyword spam;
+- generated Markdown links resolve to the intended stable module address;
+- rebuilding the same source state produces the same generated artifacts.
+
+Generated output is a review aid, not a replacement for source review. The catalog, schemas, maturity metadata, comparison definitions, and module sources remain the authoritative inputs.

docs/KIND_EDITORIAL_CHECKLISTS.md

@@ -0,0 +1,104 @@
+# Kind-specific editorial checklists
+
+Use these prompts after the general module standard and deepening checklist. They are review aids, not rigid section templates: omit a prompt when it is genuinely irrelevant and explain unusual scope choices in the pull request.
+
+## Tools
+
+- Explain the task boundary: what the tool owns and what it deliberately delegates.
+- Show the normal workflow from input/configuration through observable output.
+- Document important local, remote, cache, state, and credential boundaries.
+- Include failure recovery for interrupted or partially successful operations.
+- Distinguish convenience defaults from production-safe practice.
+- Cover plugin/extension or supply-chain risk when third-party code is executable.
+- Compare at least one credible alternative on workflow and operational trade-offs.
+
+## Languages and runtimes
+
+- Separate language semantics from compiler/interpreter/runtime implementation details.
+- Explain execution and memory models at the depth appropriate to module maturity.
+- Identify concurrency, error, module/package, and interoperability boundaries.
+- Note compatibility/versioning commitments and common migration hazards.
+- Include representative build/run/debug/test workflows rather than syntax catalogs.
+- Cover package/dependency supply-chain controls where applicable.
+
+## Frameworks and libraries
+
+- State the abstraction the framework provides and what remains application-owned.
+- Explain lifecycle, dependency injection/state/data-flow, extension, and configuration models where relevant.
+- Distinguish framework behavior from host language/runtime/platform behavior.
+- Document performance costs, deployment constraints, upgrade boundaries, and escape hatches.
+- Include testing, observability, and failure-debugging workflows.
+- Compare alternatives using architectural fit rather than popularity.
+
+## Cloud, infrastructure, and distributed systems
+
+- Draw clear control-plane, data-plane, and trust boundaries.
+- Explain reconciliation, scheduling, replication, consistency, or orchestration semantics as applicable.
+- Identify durable state, identity, tenancy, region/failure-domain, and network assumptions.
+- Cover rollout, rollback, backup/restore, disaster recovery, and degraded-mode behavior.
+- Include capacity, latency, cost, security, and availability trade-offs.
+- Make managed-service versus self-hosted responsibility boundaries explicit.
+
+## Databases and storage
+
+- Explain logical data model and physical/storage-engine boundaries separately.
+- Cover transactions, isolation/concurrency, locking or conflict behavior, and durability.
+- Describe indexing/query-planning or access-path behavior where relevant.
+- Include backup, restore, replication, failover, corruption/integrity, and migration workflows.
+- State consistency and filesystem/network assumptions.
+- Connect tuning advice to measurable bottlenecks instead of generic settings lists.
+
+## Security, cryptography, and privacy
+
+- State threat model, protected assets, attacker capabilities, and out-of-scope assumptions.
+- Separate preventive, detective, recovery, and operational controls.
+- Prefer standards, specifications, vendor advisories, and primary security documentation for consequential claims.
+- Avoid presenting configuration snippets as universally safe defaults.
+- Cover key/secret lifecycle, trust anchors, identity, logging, update, and compromise-recovery boundaries when applicable.
+- Time-scope rapidly changing vulnerability or advisory claims and record verification dates.
+
+## Protocols and standards
+
+- Identify authoritative specification versions and status.
+- Explain actors, state machines, message/data model, negotiation, and failure semantics.
+- Separate normative requirements from common implementation choices.
+- Cover compatibility, extension/versioning, security, privacy, and deployment assumptions.
+- Include at least one end-to-end exchange or workflow when it improves understanding.
+- Note important interoperability tests or implementation pitfalls.
+
+## AI and machine learning
+
+- Distinguish model architecture, training/inference system, product wrapper, and deployment runtime.
+- State data, compute, evaluation, latency, cost, privacy, and safety assumptions.
+- Explain inputs/outputs, context/state behavior, failure modes, and observability.
+- Avoid benchmark claims without dataset, metric, version, and evaluation context.
+- Cover reproducibility and model/dependency provenance where practical.
+- Compare alternatives by workload and constraints rather than headline capability.
+
+## Concepts
+
+- Define the concept independently of any single implementation or vendor.
+- Explain the mental model, invariants, and boundaries before examples.
+- Use multiple implementations when that prevents accidental product-specific framing.
+- Include common misconceptions, failure modes, and trade-offs.
+- Link naturally to prerequisite and next-step modules without manufacturing graph edges.
+
+## Open-source projects and ecosystems
+
+- Separate project governance, technical architecture, distribution, and hosted/commercial offerings.
+- Identify upstream release/support policy and dependency/plugin ecosystem boundaries.
+- Explain contribution, extension, upgrade, and compatibility models where relevant.
+- Cover supply-chain, maintainer, signing/release, and provenance considerations for critical projects.
+- Avoid equating repository activity or popularity with technical quality.
+
+## Final kind-aware review
+
+Before requesting review, verify that:
+
+1. the module's kind-specific architecture and ownership boundaries are clear;
+2. practical workflows are present where the subject is operational;
+3. consequential security/reliability claims are source-backed and appropriately scoped;
+4. trade-offs and alternatives are technically fair;
+5. version-sensitive statements identify their scope or verification date;
+6. links and relationships help readers navigate rather than inflate graph density;
+7. the module still satisfies the general `MODULE_STANDARD.md` and repository validation rules.