docs: update gcode wiki files with degradation metadata and source references

Author: joshwilhelmi

gobby-wiki/code/files/crates/gcode/assets/import_roots/elixir_dependency_roots.json.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/assets/import_roots/elixir_dependency_roots.json
@@ -14,11 +17,9 @@ Module: [[code/modules/crates/gcode/assets/import_roots|crates/gcode/assets/impo
 
 ## Overview
 
-`crates/gcode/assets/import_roots/elixir_dependency_roots.json` exposes 16 indexed API symbols.
-
 ## How it fits
 
-`crates/gcode/assets/import_roots/elixir_dependency_roots.json` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+For example, when a project references JSON or HTTP client packages, the indexer maps `jason` [crates/gcode/assets/import_roots/elixir_dependency_roots.json:2] to `Jason`, and `httpoison` [crates/gcode/assets/import_roots/elixir_dependency_roots.json:3] or `tesla` [crates/gcode/assets/import_roots/elixir_dependency_roots.json:4] to their respective module roots. Similarly, modern HTTP clients like `req` [crates/gcode/assets/import_roots/elixir_dependency_roots.json:5], `finch` [crates/gcode/assets/import_roots/elixir_dependency_roots.json:6], and `mint` [crates/gcode/assets/import_roots/elixir_dependency_roots.json:7] are associated with their exact module signatures.
 
 ## Key components
 

gobby-wiki/code/files/crates/gcode/assets/import_roots/ruby_require_roots.json.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/assets/import_roots/ruby_require_roots.json
@@ -14,11 +17,12 @@ Module: [[code/modules/crates/gcode/assets/import_roots|crates/gcode/assets/impo
 
 ## Overview
 
-`crates/gcode/assets/import_roots/ruby_require_roots.json` exposes 10 indexed API symbols.
-
 ## How it fits
-
-`crates/gcode/assets/import_roots/ruby_require_roots.json` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+[crates/gcode/assets/import_roots/ruby_require_roots.json:2]
+[crates/gcode/assets/import_roots/ruby_require_roots.json:3]
+[crates/gcode/assets/import_roots/ruby_require_roots.json:4]
+[crates/gcode/assets/import_roots/ruby_require_roots.json:5]
+[crates/gcode/assets/import_roots/ruby_require_roots.json:6]
 
 ## Key components
 

gobby-wiki/code/files/crates/gcode/build.rs.md

@@ -6,23 +6,23 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/build.rs
 
 Module: [[code/modules/crates/gcode|crates/gcode]]
 
 ## Overview
+This file serves as the Cargo build script for the `gcode` crate, managing compile-time environment configuration and feature flags crates/gcode/build.rs:1-8. Its primary role is to set up conditional compilation based on the presence of a test database.
 
-`crates/gcode/build.rs` exposes 1 indexed API symbol.
-
-## How it fits
-
-`crates/gcode/build.rs` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+The script ensures that the build is re-evaluated whenever the `GCODE_POSTGRES_TEST_DATABASE_URL` environment variable changes crates/gcode/build.rs:2. It also registers the custom `gcode_postgres_tests` configuration flag with the compiler to prevent unexpected configuration warnings crates/gcode/build.rs:3. [crates/gcode/build.rs:1-8]
 
 ## Key components
 
 | Symbol | Kind | Purpose |
 | --- | --- | --- |
-| `main` | function | Indexed function `main` in `crates/gcode/build.rs`. [crates/gcode/build.rs:1-8] |
+| `main` | function | Emits Cargo build-script directives to rerun when 'GCODE_POSTGRES_TEST_DATABASE_URL' changes, register the 'gcode_postgres_tests' cfg for check-cfg, and enable that cfg when the environment variable is set. [crates/gcode/build.rs:1-8] |
 

gobby-wiki/code/files/crates/gcode/contract/gcode.contract.json.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/contract/gcode.contract.json
@@ -14,11 +17,12 @@ Module: [[code/modules/crates/gcode/contract|crates/gcode/contract]]
 
 ## Overview
 
-`crates/gcode/contract/gcode.contract.json` exposes 952 indexed API symbols.
-
 ## How it fits
-
-`crates/gcode/contract/gcode.contract.json` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+[crates/gcode/contract/gcode.contract.json:2]
+[crates/gcode/contract/gcode.contract.json:3]
+[crates/gcode/contract/gcode.contract.json:4]
+[crates/gcode/contract/gcode.contract.json:5-49]
+[crates/gcode/contract/gcode.contract.json:7]
 
 ## Key components
 

gobby-wiki/code/files/crates/gcode/src/cli.rs.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/src/cli.rs
@@ -14,11 +17,20 @@ Module: [[code/modules/crates/gcode/src|crates/gcode/src]]
 
 ## Overview
 
-`crates/gcode/src/cli.rs` exposes 14 indexed API symbols.
+The crates/gcode/src/cli.rs file defines the command-line interface entry point and configuration structures for the gcode command-line utility. It acts as the user-facing gateway that parses CLI inputs, validates configuration parameters, and routes commands to the appropriate execution paths.
+
+The main structure is the Cli struct, which is a crate-private Clap-parsed top-level command-line configuration struct (crates/gcode/src/cli.rs:23-46). This struct captures global settings like the project root, output format, verbose logging, quiet mode, and freshness checks.
 
 ## How it fits
 
-`crates/gcode/src/cli.rs` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+This file serves as the translator between external CLI arguments and core library data types. By mapping command-line options into internal structures, it establishes the foundation for downstream data flow across Gobby crates.
+
+It exposes several arguments and direct translation functions. The AiRouteArg enum (crates/gcode/src/cli.rs:49-54) and its From implementation (crates/gcode/src/cli.rs:57-64) map string-based user arguments directly onto Gobby's core AiRouting variants. Similarly, the AiDepthArg enum (crates/gcode/src/cli.rs:68-73) and its From converter (crates/gcode/src/cli.rs:76-82) translate command options into core Gobby code wiki parameters.
+[crates/gcode/src/cli.rs:23-46]
+[crates/gcode/src/cli.rs:49-54]
+[crates/gcode/src/cli.rs:57-64]
+[crates/gcode/src/cli.rs:68-73]
+[crates/gcode/src/cli.rs:76-82]
 
 ## Key components
 

gobby-wiki/code/files/crates/gcode/src/cli/tests.rs.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/src/cli/tests.rs
@@ -14,17 +17,17 @@ Module: [[code/modules/crates/gcode/src/cli|crates/gcode/src/cli]]
 
 ## Overview
 
-`crates/gcode/src/cli/tests.rs` exposes 3 indexed API symbols.
-
 ## How it fits
 
-`crates/gcode/src/cli/tests.rs` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+The file bridges the runtime command-line parser with the system's external interface contract. The main test function, clap_command_leaves_are_documented_in_contract [crates/gcode/src/cli/tests.rs:12-30], generates the active command structure using the clap parser and extracts its leaves.
+
+To retrieve these leaves, the test utilizes clap_command_leaves [crates/gcode/src/cli/tests.rs:32-36], which delegates to collect_clap_command_leaves [crates/gcode/src/cli/tests.rs:38-55]. This helper function recursively traverses the subcommand hierarchy, constructing space-delimited string paths for each leaf command.
 
 ## Key components
 
 | Symbol | Kind | Purpose |
 | --- | --- | --- |
-| `clap_command_leaves_are_documented_in_contract` | function | Indexed function `clap_command_leaves_are_documented_in_contract` in `crates/gcode/src/cli/tests.rs`. [crates/gcode/src/cli/tests.rs:12-30] |
-| `clap_command_leaves` | function | Indexed function `clap_command_leaves` in `crates/gcode/src/cli/tests.rs`. [crates/gcode/src/cli/tests.rs:32-36] |
-| `collect_clap_command_leaves` | function | Indexed function `collect_clap_command_leaves` in `crates/gcode/src/cli/tests.rs`. [crates/gcode/src/cli/tests.rs:38-55] |
+| `clap_command_leaves_are_documented_in_contract` | function | Verifies that every leaf command exposed by 'Cli::command()' via 'clap_command_leaves' has a corresponding entry in the Gobby contract, failing with a list of missing command names if any are absent. [crates/gcode/src/cli/tests.rs:12-30] |
+| `clap_command_leaves` | function | Returns the set of leaf command names reachable from the given 'clap::Command' by recursively collecting them into a 'BTreeSet<String>'. [crates/gcode/src/cli/tests.rs:32-36] |
+| `collect_clap_command_leaves` | function | Recursively traverses a 'clap::Command' subtree, building space-delimited subcommand paths from an optional prefix and inserting the full paths of all leaf subcommands into the provided 'BTreeSet<String>'. [crates/gcode/src/cli/tests.rs:38-55] |
 

gobby-wiki/code/files/crates/gcode/src/commands/codewiki/build.rs.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/src/commands/codewiki/build.rs
@@ -14,11 +17,11 @@ Module: [[code/modules/crates/gcode/src/commands/codewiki|crates/gcode/src/comma
 
 ## Overview
 
-`crates/gcode/src/commands/codewiki/build.rs` has no indexed API symbols.
+By consolidating these modules, the file re-exports specialized functions designed to build specific documentation segments, as shown in `crates/gcode/src/commands/codewiki/build.rs:21-30`. These builder functions facilitate the generation of structured content such as onboarding guides, module documentation, hotspots, and architecture overviews.
 
 ## How it fits
 
-`crates/gcode/src/commands/codewiki/build.rs` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+Additionally, the file defines structural modularity by mapping the submodules to distinct physical files using path attributes, as declared in `crates/gcode/src/commands/codewiki/build.rs:1-19`. This separation of concerns allows developers to manage individual document builders in isolated files while maintaining a single, clean API boundary in this module for the broader `codewiki` command operations. [crates/gcode/src/commands/codewiki/build.rs:1-30]
 
 ## Key components
 

gobby-wiki/code/files/crates/gcode/src/commands/codewiki/build_parts/architecture.rs.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/src/commands/codewiki/build_parts/architecture.rs
@@ -14,11 +17,16 @@ Module: [[code/modules/crates/gcode/src/commands/codewiki/build_parts|crates/gco
 
 ## Overview
 
-`crates/gcode/src/commands/codewiki/build_parts/architecture.rs` exposes 3 indexed API symbols.
+This file is responsible for constructing high-level architectural documentation for a codebase in the form of an ArchitectureDoc. It analyzes files, modules, and dependency relationships to map out how the system is organized.
+
+The main driver in this file is build_architecture_doc crates/gcode/src/commands/codewiki/build_parts/architecture.rs:5-169. It groups files into logical subsystems, compiles subsystem-level summaries, and tracks the availability of dependency graph data, flagging the documentation as degraded if graph data is truncated or unavailable.
 
 ## How it fits
 
-`crates/gcode/src/commands/codewiki/build_parts/architecture.rs` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+This file is a key component of the codewiki documentation-generation engine. It takes raw file listings, module definitions, and dependency edges, and refines them into a structured representation of the system layout and hierarchy.
+[crates/gcode/src/commands/codewiki/build_parts/architecture.rs:5-169]
+[crates/gcode/src/commands/codewiki/build_parts/architecture.rs:175-190]
+[crates/gcode/src/commands/codewiki/build_parts/architecture.rs:193-243]
 
 ## Key components
 

gobby-wiki/code/files/crates/gcode/src/commands/codewiki/build_parts/changes.rs.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/src/commands/codewiki/build_parts/changes.rs
@@ -14,11 +17,18 @@ Module: [[code/modules/crates/gcode/src/commands/codewiki/build_parts|crates/gco
 
 ## Overview
 
-`crates/gcode/src/commands/codewiki/build_parts/changes.rs` exposes 5 indexed API symbols.
+The `crates/gcode/src/commands/codewiki/build_parts/changes.rs` file is responsible for generating structured Markdown change reports that document modifications between codebase index snapshots. It provides developers and automated systems with a clear mechanism to trace files and symbols that have been introduced, modified, or removed across different versions of the codebase index.
+
+At the core of this file is the `build_codewiki_changes_doc` function in `crates/gcode/src/commands/codewiki/build_parts/changes.rs:5-101`. This function acts as the generator for the change report, accepting current and optional previous snapshot states to determine changes in files, symbols, and dependency graph neighborhoods. If no previous index snapshot exists, the file gracefully generates a baseline report indicating that this is the initial snapshot.
 
 ## How it fits
 
-`crates/gcode/src/commands/codewiki/build_parts/changes.rs` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+The main data flow starts with `build_codewiki_changes_doc` in `crates/gcode/src/commands/codewiki/build_parts/changes.rs:5-101`, which compares the keys of the file and symbol maps of the previous and current snapshots. It computes sets of added, removed, and modified files by cross-referencing keys and comparing content hashes.
+[crates/gcode/src/commands/codewiki/build_parts/changes.rs:5-101]
+[crates/gcode/src/commands/codewiki/build_parts/changes.rs:104-113]
+[crates/gcode/src/commands/codewiki/build_parts/changes.rs:115-138]
+[crates/gcode/src/commands/codewiki/build_parts/changes.rs:140-156]
+[crates/gcode/src/commands/codewiki/build_parts/changes.rs:158-163]
 
 ## Key components
 

gobby-wiki/code/files/crates/gcode/src/commands/codewiki/build_parts/concepts.rs.md

@@ -6,6 +6,9 @@ provenance:
 generated_by: gcode-codewiki
 trust: generated
 freshness: indexed
+degraded: true
+degraded_sources:
+- model-unavailable
 ---
 
 # crates/gcode/src/commands/codewiki/build_parts/concepts.rs
@@ -14,11 +17,20 @@ Module: [[code/modules/crates/gcode/src/commands/codewiki/build_parts|crates/gco
 
 ## Overview
 
-`crates/gcode/src/commands/codewiki/build_parts/concepts.rs` exposes 6 indexed API symbols.
+This file serves as the coordinator for building curated conceptual and navigation documentation within the Codewiki build pipeline. It is responsible for orchestrating high-level overview documentation and guided tours, ensuring they remain digestible and structurally bounded.
+
+A primary role of this file is to define structural constraints for curated documentation. It defines constants that cap the number of narrative chapters and limit list lengths, such as the maximum number of key components and source file links. These constraints prevent verbose automated outputs from overwhelming the final user-facing documentation structure.
 
 ## How it fits
 
-`crates/gcode/src/commands/codewiki/build_parts/concepts.rs` is documented from its indexed symbols; see the Key components below and the module page for how it connects to sibling files.
+This file represents a key module entry point, delegating specific processing tasks to its path-declared submodules including plan, render, spans, support, and types. It integrates directly with the broader Codewiki build system by consuming arrays of FileDoc and ModuleDoc structures.
+
+During the documentation generation flow, the build process extracts all input spans to evaluate document freshness. If the reuse planner confirms that source spans are unchanged, previously compiled markdown pages under the concepts and narrative paths are returned directly, saving translation and processing overhead.
+[crates/gcode/src/commands/codewiki/build_parts/concepts.rs:35-85]
+[crates/gcode/src/commands/codewiki/build_parts/concepts.rs:93-110]
+[crates/gcode/src/commands/codewiki/build_parts/concepts.rs:113-124]
+[crates/gcode/src/commands/codewiki/build_parts/concepts.rs:127-137]
+[crates/gcode/src/commands/codewiki/build_parts/concepts.rs:140-152]
 
 ## Key components