agent-wiki-cli 1.2.0__tar.gz → 1.3.0__tar.gz

{agent_wiki_cli-1.2.0/src/agent_wiki_cli.egg-info → agent_wiki_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 1.2.0
+Version: 1.3.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -17,6 +17,7 @@ Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6
 Requires-Dist: tomli>=2; python_version < "3.11"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
@@ -53,6 +54,7 @@ canonical wiki surface registry:
 | `guides/` | semantic | Agent-authored onboarding, operator, and contributor guides. |
 | `flows/` | mixed | User-flow pages, one per detected entry point, with bounded generated Mermaid call and data-flow diagrams. |
 | `infrastructure/` | mixed | Dockerfile, Compose, GitHub Actions, Kubernetes, and targeted runtime/config YAML pages. |
+| `api-contracts.md` | mixed | Optional production HTTP contract inventory generated from static FastAPI declarations or an exported OpenAPI document; `## Notes` is semantic. |
 | `dependencies.md` | mixed | Optional internal and external dependency architecture page. |
 | `load-order.md` | mixed | Optional load-order, cycle, and startup-caveat architecture page. |
 
@@ -88,8 +90,11 @@ plain, MkDocs-compatible, or Docusaurus-compatible Markdown output without
 invoking external builders. Static-site output is a derived artifact; it must
 not become a second editable source of truth.
 
-The package has no required Python runtime dependencies. Optional features use
-external tools when they are available on `PATH`.
+The package has a small required Python runtime footprint. `PyYAML>=6` parses
+user-supplied OpenAPI YAML, and Python versions older than 3.11 use `tomli` for
+TOML. FastAPI, Pydantic, and the target application are not runtime
+dependencies and are never imported for contract extraction. Optional language
+features use external tools when they are available on `PATH`.
 
 ## Supported Inputs
 
@@ -102,6 +107,7 @@ external tools when they are available on `PATH`.
 | Haskell | bundled GHC parser helper for syntax-only inventory | prepared helper binary |
 | Docker / Compose | built-in parsers | none |
 | Runtime/config YAML | targeted built-in parsers | none |
+| OpenAPI 3.0/3.1 JSON / YAML | stdlib `json` / PyYAML safe loader | `PyYAML>=6` (installed with the package) |
 | MCP server | official Python MCP SDK | `agent-wiki-cli[mcp]`, Python 3.10+ |
 
 TypeScript/JavaScript, Go, Rust, and Haskell helper setup is explicit; prepare
@@ -310,6 +316,8 @@ llm-wiki bootstrap --skip-workflows
 llm-wiki bootstrap --skip-flows
 llm-wiki bootstrap --skip-data-flow
 llm-wiki bootstrap --skip-dependencies
+llm-wiki bootstrap --api-contracts
+llm-wiki bootstrap --api-contracts --openapi-file openapi.yaml
 llm-wiki bootstrap --include-tests go
 llm-wiki bootstrap --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki bootstrap --format json --source-adapter
@@ -328,6 +336,12 @@ Dependency architecture pages are generated as `dependencies.md` and
 pages or lint diagnostics. Generated `index.md` is a registry-backed landing
 page with a surface overview table, per-surface counts, grouped user-flow
 entries, optional dependency architecture links, and a direct log link.
+`--api-contracts` adds the optional `api-contracts.md` production HTTP
+inventory and generated API-contract sections on matching HTTP flow pages.
+Passing `--openapi-file` implies `--api-contracts`; the supplied OpenAPI 3.0 or
+3.1 JSON/YAML document is authoritative for wire fields, while syntax-only
+source analysis contributes handler, module, entity, and flow links. The target
+application is never imported or executed.
 `--depth full` is the default and includes
 docstrings, imports, attributes, method signatures, generated relationship
 sections, bounded per-module dependency mini-map summaries, and diagram data
@@ -356,6 +370,8 @@ llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
+llm-wiki sync --initialize-surfaces api-contracts --openapi-file openapi.yaml --dry-run
 llm-wiki sync --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src
 ```
 
@@ -371,6 +387,14 @@ languages and plugin extractors whose manifests set `"parallel_safe": true`.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
+`--initialize-surfaces` enters a surface-only backfill mode for `flows`,
+`dependencies`, and/or `api-contracts`: ordinary entity/module source changes
+are reported but deferred. `--flow-category` is repeatable, `--exclude-tests`
+uses a cross-platform test-path classifier for the selected flow/dependency
+analysis, and `--dry-run` previews exact page counts and safety-guard results
+without writing the wiki, manifest, log, index, surface index, or cache.
+Selected flow categories and test filtering are persisted in manifest v4 so a
+later ordinary sync cannot silently expand an HTTP-only backfill to every flow.
 Pass `--include-tests go` to include Go `_test.go` files in the synced
 inventory and generated module pages; the default remains production Go source
 only.
@@ -404,6 +428,13 @@ When flow pages already exist, `sync` also refreshes generated call-sequence and
 `## Data flow` content from the current inventory while preserving the
 human-authored `## Behavior` section by default.
 
+When `api-contracts.md` exists, sync refreshes its generated operation inventory
+and matching flow-page contract sections while preserving `## Notes` and
+`## Behavior`. A bootstrap/sync OpenAPI input is stored as a source-relative
+path and hash; a specification-only change refreshes contracts even when source
+files are unchanged. Use `--clear-openapi-file` to return deliberately to
+static contract authority.
+
 When `sync` rebuilds `index.md`, the generated landing-page overview and
 per-surface link sections are replaced from the live registry and inventory.
 With semantic preservation enabled, old custom top-level index sections are
@@ -421,6 +452,7 @@ llm-wiki extract --src-dir .
 llm-wiki extract --src-dir . --changed
 llm-wiki extract --src-dir . --summary
 llm-wiki extract --src-dir . --deep
+llm-wiki extract --src-dir . --deep --openapi-file openapi.json
 llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
 llm-wiki extract --src-dir . --package llm_wiki_cli
 llm-wiki extract --src-dir . --include-empty
@@ -473,7 +505,13 @@ With `--deep`, Python function entries may carry optional `data_effects` blocks
 (inputs, selected global/attribute reads, writes, returns, and boundary effects
 such as filesystem, environment, process, network, output, and logging calls)
 and optional `calls` lists (in-body call targets, optionally with compact `args`
-and `kwargs` expression summaries). The payload also gains an optional top-level
+and `kwargs` expression summaries). Function `params` include reconstructable
+parameter kinds for positional-only, positional-or-keyword, variadic,
+keyword-only, and variadic-keyword declarations. Python model/type inventory
+also carries optional required/nullable/default/factory, alias, constraint,
+description/example, `Annotated`, validator/config, enum-member, literal, and
+type-alias metadata without importing Pydantic or application modules.
+The payload also gains an optional top-level
 `entrypoints` array (detected user-reachable entry points: `{id, category, file,
 symbol, label}`), a `data_flows` list for detected user flows, plus a top-level
 `dependencies` object with internal `edges`, `cycles`, per-language external
@@ -489,6 +527,13 @@ keys are POSIX paths relative to `--src-dir`, never absolute paths. The v1
 contract permits additive fields; incompatible shape changes require a new
 schema version. The M3 data-flow fields are therefore optional additions under
 `llm-wiki-extract/v1`, not a schema bump.
+Deep Python extraction also emits optional per-file `frameworks.fastapi`
+declarations and a top-level `api_contracts` object. Static uncertainty is
+reported through `unknowns` and diagnostics; test-source and
+`include_in_schema=False` operations are excluded from the production operation
+inventory by default. With `--openapi-file`, OpenAPI defines the operation set
+and wire contract, external references are never fetched, and unmatched or
+conflicting static declarations remain visible as diagnostics.
 Installed `entrypoint_detector` plugin hooks also contribute to the same
 `entrypoints` array in deep output. Detector failures are isolated: built-in
 entry-point detection still runs, `extract` prints a warning to stderr, and the

{agent_wiki_cli-1.2.0 → agent_wiki_cli-1.3.0}/README.md

@@ -23,6 +23,7 @@ canonical wiki surface registry:
 | `guides/` | semantic | Agent-authored onboarding, operator, and contributor guides. |
 | `flows/` | mixed | User-flow pages, one per detected entry point, with bounded generated Mermaid call and data-flow diagrams. |
 | `infrastructure/` | mixed | Dockerfile, Compose, GitHub Actions, Kubernetes, and targeted runtime/config YAML pages. |
+| `api-contracts.md` | mixed | Optional production HTTP contract inventory generated from static FastAPI declarations or an exported OpenAPI document; `## Notes` is semantic. |
 | `dependencies.md` | mixed | Optional internal and external dependency architecture page. |
 | `load-order.md` | mixed | Optional load-order, cycle, and startup-caveat architecture page. |
 
@@ -58,8 +59,11 @@ plain, MkDocs-compatible, or Docusaurus-compatible Markdown output without
 invoking external builders. Static-site output is a derived artifact; it must
 not become a second editable source of truth.
 
-The package has no required Python runtime dependencies. Optional features use
-external tools when they are available on `PATH`.
+The package has a small required Python runtime footprint. `PyYAML>=6` parses
+user-supplied OpenAPI YAML, and Python versions older than 3.11 use `tomli` for
+TOML. FastAPI, Pydantic, and the target application are not runtime
+dependencies and are never imported for contract extraction. Optional language
+features use external tools when they are available on `PATH`.
 
 ## Supported Inputs
 
@@ -72,6 +76,7 @@ external tools when they are available on `PATH`.
 | Haskell | bundled GHC parser helper for syntax-only inventory | prepared helper binary |
 | Docker / Compose | built-in parsers | none |
 | Runtime/config YAML | targeted built-in parsers | none |
+| OpenAPI 3.0/3.1 JSON / YAML | stdlib `json` / PyYAML safe loader | `PyYAML>=6` (installed with the package) |
 | MCP server | official Python MCP SDK | `agent-wiki-cli[mcp]`, Python 3.10+ |
 
 TypeScript/JavaScript, Go, Rust, and Haskell helper setup is explicit; prepare
@@ -280,6 +285,8 @@ llm-wiki bootstrap --skip-workflows
 llm-wiki bootstrap --skip-flows
 llm-wiki bootstrap --skip-data-flow
 llm-wiki bootstrap --skip-dependencies
+llm-wiki bootstrap --api-contracts
+llm-wiki bootstrap --api-contracts --openapi-file openapi.yaml
 llm-wiki bootstrap --include-tests go
 llm-wiki bootstrap --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki bootstrap --format json --source-adapter
@@ -298,6 +305,12 @@ Dependency architecture pages are generated as `dependencies.md` and
 pages or lint diagnostics. Generated `index.md` is a registry-backed landing
 page with a surface overview table, per-surface counts, grouped user-flow
 entries, optional dependency architecture links, and a direct log link.
+`--api-contracts` adds the optional `api-contracts.md` production HTTP
+inventory and generated API-contract sections on matching HTTP flow pages.
+Passing `--openapi-file` implies `--api-contracts`; the supplied OpenAPI 3.0 or
+3.1 JSON/YAML document is authoritative for wire fields, while syntax-only
+source analysis contributes handler, module, entity, and flow links. The target
+application is never imported or executed.
 `--depth full` is the default and includes
 docstrings, imports, attributes, method signatures, generated relationship
 sections, bounded per-module dependency mini-map summaries, and diagram data
@@ -326,6 +339,8 @@ llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
+llm-wiki sync --initialize-surfaces api-contracts --openapi-file openapi.yaml --dry-run
 llm-wiki sync --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src
 ```
 
@@ -341,6 +356,14 @@ languages and plugin extractors whose manifests set `"parallel_safe": true`.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
+`--initialize-surfaces` enters a surface-only backfill mode for `flows`,
+`dependencies`, and/or `api-contracts`: ordinary entity/module source changes
+are reported but deferred. `--flow-category` is repeatable, `--exclude-tests`
+uses a cross-platform test-path classifier for the selected flow/dependency
+analysis, and `--dry-run` previews exact page counts and safety-guard results
+without writing the wiki, manifest, log, index, surface index, or cache.
+Selected flow categories and test filtering are persisted in manifest v4 so a
+later ordinary sync cannot silently expand an HTTP-only backfill to every flow.
 Pass `--include-tests go` to include Go `_test.go` files in the synced
 inventory and generated module pages; the default remains production Go source
 only.
@@ -374,6 +397,13 @@ When flow pages already exist, `sync` also refreshes generated call-sequence and
 `## Data flow` content from the current inventory while preserving the
 human-authored `## Behavior` section by default.
 
+When `api-contracts.md` exists, sync refreshes its generated operation inventory
+and matching flow-page contract sections while preserving `## Notes` and
+`## Behavior`. A bootstrap/sync OpenAPI input is stored as a source-relative
+path and hash; a specification-only change refreshes contracts even when source
+files are unchanged. Use `--clear-openapi-file` to return deliberately to
+static contract authority.
+
 When `sync` rebuilds `index.md`, the generated landing-page overview and
 per-surface link sections are replaced from the live registry and inventory.
 With semantic preservation enabled, old custom top-level index sections are
@@ -391,6 +421,7 @@ llm-wiki extract --src-dir .
 llm-wiki extract --src-dir . --changed
 llm-wiki extract --src-dir . --summary
 llm-wiki extract --src-dir . --deep
+llm-wiki extract --src-dir . --deep --openapi-file openapi.json
 llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
 llm-wiki extract --src-dir . --package llm_wiki_cli
 llm-wiki extract --src-dir . --include-empty
@@ -443,7 +474,13 @@ With `--deep`, Python function entries may carry optional `data_effects` blocks
 (inputs, selected global/attribute reads, writes, returns, and boundary effects
 such as filesystem, environment, process, network, output, and logging calls)
 and optional `calls` lists (in-body call targets, optionally with compact `args`
-and `kwargs` expression summaries). The payload also gains an optional top-level
+and `kwargs` expression summaries). Function `params` include reconstructable
+parameter kinds for positional-only, positional-or-keyword, variadic,
+keyword-only, and variadic-keyword declarations. Python model/type inventory
+also carries optional required/nullable/default/factory, alias, constraint,
+description/example, `Annotated`, validator/config, enum-member, literal, and
+type-alias metadata without importing Pydantic or application modules.
+The payload also gains an optional top-level
 `entrypoints` array (detected user-reachable entry points: `{id, category, file,
 symbol, label}`), a `data_flows` list for detected user flows, plus a top-level
 `dependencies` object with internal `edges`, `cycles`, per-language external
@@ -459,6 +496,13 @@ keys are POSIX paths relative to `--src-dir`, never absolute paths. The v1
 contract permits additive fields; incompatible shape changes require a new
 schema version. The M3 data-flow fields are therefore optional additions under
 `llm-wiki-extract/v1`, not a schema bump.
+Deep Python extraction also emits optional per-file `frameworks.fastapi`
+declarations and a top-level `api_contracts` object. Static uncertainty is
+reported through `unknowns` and diagnostics; test-source and
+`include_in_schema=False` operations are excluded from the production operation
+inventory by default. With `--openapi-file`, OpenAPI defines the operation set
+and wire contract, external references are never fetched, and unmatched or
+conflicting static declarations remain visible as diagnostics.
 Installed `entrypoint_detector` plugin hooks also contribute to the same
 `entrypoints` array in deep output. Detector failures are isolated: built-in
 entry-point detection still runs, `extract` prints a warning to stderr, and the

{agent_wiki_cli-1.2.0 → agent_wiki_cli-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-wiki-cli"
-version = "1.2.0"
+version = "1.3.0"
 description = "CLI tool to maintain hybrid LLM Wikis for multi-language projects."
 readme = "README.md"
 license = {text = "MIT"}
@@ -22,6 +22,7 @@ classifiers = [
     "Topic :: Software Development :: Documentation",
 ]
 dependencies = [
+    "PyYAML>=6",
     "tomli>=2; python_version < '3.11'",
 ]
 
@@ -89,6 +90,8 @@ where = ["src"]
     "skills/user-docs-author/reference.md",
     "skills/wiki-bootstrap/SKILL.md",
     "skills/wiki-bootstrap/reference.md",
+    "skills/wiki-reference/SKILL.md",
+    "skills/wiki-reference/reference.md",
     "skills/wiki-sync/SKILL.md",
     "skills/wiki-sync/reference.md",
 ]

{agent_wiki_cli-1.2.0 → agent_wiki_cli-1.3.0/src/agent_wiki_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 1.2.0
+Version: 1.3.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -17,6 +17,7 @@ Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6
 Requires-Dist: tomli>=2; python_version < "3.11"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
@@ -53,6 +54,7 @@ canonical wiki surface registry:
 | `guides/` | semantic | Agent-authored onboarding, operator, and contributor guides. |
 | `flows/` | mixed | User-flow pages, one per detected entry point, with bounded generated Mermaid call and data-flow diagrams. |
 | `infrastructure/` | mixed | Dockerfile, Compose, GitHub Actions, Kubernetes, and targeted runtime/config YAML pages. |
+| `api-contracts.md` | mixed | Optional production HTTP contract inventory generated from static FastAPI declarations or an exported OpenAPI document; `## Notes` is semantic. |
 | `dependencies.md` | mixed | Optional internal and external dependency architecture page. |
 | `load-order.md` | mixed | Optional load-order, cycle, and startup-caveat architecture page. |
 
@@ -88,8 +90,11 @@ plain, MkDocs-compatible, or Docusaurus-compatible Markdown output without
 invoking external builders. Static-site output is a derived artifact; it must
 not become a second editable source of truth.
 
-The package has no required Python runtime dependencies. Optional features use
-external tools when they are available on `PATH`.
+The package has a small required Python runtime footprint. `PyYAML>=6` parses
+user-supplied OpenAPI YAML, and Python versions older than 3.11 use `tomli` for
+TOML. FastAPI, Pydantic, and the target application are not runtime
+dependencies and are never imported for contract extraction. Optional language
+features use external tools when they are available on `PATH`.
 
 ## Supported Inputs
 
@@ -102,6 +107,7 @@ external tools when they are available on `PATH`.
 | Haskell | bundled GHC parser helper for syntax-only inventory | prepared helper binary |
 | Docker / Compose | built-in parsers | none |
 | Runtime/config YAML | targeted built-in parsers | none |
+| OpenAPI 3.0/3.1 JSON / YAML | stdlib `json` / PyYAML safe loader | `PyYAML>=6` (installed with the package) |
 | MCP server | official Python MCP SDK | `agent-wiki-cli[mcp]`, Python 3.10+ |
 
 TypeScript/JavaScript, Go, Rust, and Haskell helper setup is explicit; prepare
@@ -310,6 +316,8 @@ llm-wiki bootstrap --skip-workflows
 llm-wiki bootstrap --skip-flows
 llm-wiki bootstrap --skip-data-flow
 llm-wiki bootstrap --skip-dependencies
+llm-wiki bootstrap --api-contracts
+llm-wiki bootstrap --api-contracts --openapi-file openapi.yaml
 llm-wiki bootstrap --include-tests go
 llm-wiki bootstrap --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki bootstrap --format json --source-adapter
@@ -328,6 +336,12 @@ Dependency architecture pages are generated as `dependencies.md` and
 pages or lint diagnostics. Generated `index.md` is a registry-backed landing
 page with a surface overview table, per-surface counts, grouped user-flow
 entries, optional dependency architecture links, and a direct log link.
+`--api-contracts` adds the optional `api-contracts.md` production HTTP
+inventory and generated API-contract sections on matching HTTP flow pages.
+Passing `--openapi-file` implies `--api-contracts`; the supplied OpenAPI 3.0 or
+3.1 JSON/YAML document is authoritative for wire fields, while syntax-only
+source analysis contributes handler, module, entity, and flow links. The target
+application is never imported or executed.
 `--depth full` is the default and includes
 docstrings, imports, attributes, method signatures, generated relationship
 sections, bounded per-module dependency mini-map summaries, and diagram data
@@ -356,6 +370,8 @@ llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
+llm-wiki sync --initialize-surfaces api-contracts --openapi-file openapi.yaml --dry-run
 llm-wiki sync --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src
 ```
 
@@ -371,6 +387,14 @@ languages and plugin extractors whose manifests set `"parallel_safe": true`.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
+`--initialize-surfaces` enters a surface-only backfill mode for `flows`,
+`dependencies`, and/or `api-contracts`: ordinary entity/module source changes
+are reported but deferred. `--flow-category` is repeatable, `--exclude-tests`
+uses a cross-platform test-path classifier for the selected flow/dependency
+analysis, and `--dry-run` previews exact page counts and safety-guard results
+without writing the wiki, manifest, log, index, surface index, or cache.
+Selected flow categories and test filtering are persisted in manifest v4 so a
+later ordinary sync cannot silently expand an HTTP-only backfill to every flow.
 Pass `--include-tests go` to include Go `_test.go` files in the synced
 inventory and generated module pages; the default remains production Go source
 only.
@@ -404,6 +428,13 @@ When flow pages already exist, `sync` also refreshes generated call-sequence and
 `## Data flow` content from the current inventory while preserving the
 human-authored `## Behavior` section by default.
 
+When `api-contracts.md` exists, sync refreshes its generated operation inventory
+and matching flow-page contract sections while preserving `## Notes` and
+`## Behavior`. A bootstrap/sync OpenAPI input is stored as a source-relative
+path and hash; a specification-only change refreshes contracts even when source
+files are unchanged. Use `--clear-openapi-file` to return deliberately to
+static contract authority.
+
 When `sync` rebuilds `index.md`, the generated landing-page overview and
 per-surface link sections are replaced from the live registry and inventory.
 With semantic preservation enabled, old custom top-level index sections are
@@ -421,6 +452,7 @@ llm-wiki extract --src-dir .
 llm-wiki extract --src-dir . --changed
 llm-wiki extract --src-dir . --summary
 llm-wiki extract --src-dir . --deep
+llm-wiki extract --src-dir . --deep --openapi-file openapi.json
 llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
 llm-wiki extract --src-dir . --package llm_wiki_cli
 llm-wiki extract --src-dir . --include-empty
@@ -473,7 +505,13 @@ With `--deep`, Python function entries may carry optional `data_effects` blocks
 (inputs, selected global/attribute reads, writes, returns, and boundary effects
 such as filesystem, environment, process, network, output, and logging calls)
 and optional `calls` lists (in-body call targets, optionally with compact `args`
-and `kwargs` expression summaries). The payload also gains an optional top-level
+and `kwargs` expression summaries). Function `params` include reconstructable
+parameter kinds for positional-only, positional-or-keyword, variadic,
+keyword-only, and variadic-keyword declarations. Python model/type inventory
+also carries optional required/nullable/default/factory, alias, constraint,
+description/example, `Annotated`, validator/config, enum-member, literal, and
+type-alias metadata without importing Pydantic or application modules.
+The payload also gains an optional top-level
 `entrypoints` array (detected user-reachable entry points: `{id, category, file,
 symbol, label}`), a `data_flows` list for detected user flows, plus a top-level
 `dependencies` object with internal `edges`, `cycles`, per-language external
@@ -489,6 +527,13 @@ keys are POSIX paths relative to `--src-dir`, never absolute paths. The v1
 contract permits additive fields; incompatible shape changes require a new
 schema version. The M3 data-flow fields are therefore optional additions under
 `llm-wiki-extract/v1`, not a schema bump.
+Deep Python extraction also emits optional per-file `frameworks.fastapi`
+declarations and a top-level `api_contracts` object. Static uncertainty is
+reported through `unknowns` and diagnostics; test-source and
+`include_in_schema=False` operations are excluded from the production operation
+inventory by default. With `--openapi-file`, OpenAPI defines the operation set
+and wire contract, external references are never fetched, and unmatched or
+conflicting static declarations remain visible as diagnostics.
 Installed `entrypoint_detector` plugin hooks also contribute to the same
 `entrypoints` array in deep output. Detector failures are isolated: built-in
 entry-point detection still runs, `extract` prints a warning to stderr, and the

{agent_wiki_cli-1.2.0 → agent_wiki_cli-1.3.0}/src/agent_wiki_cli.egg-info/SOURCES.txt

@@ -47,8 +47,10 @@ src/llm_wiki_cli/examples/plugins/m4-documentation-hooks/llm-wiki-plugin.json
 src/llm_wiki_cli/examples/plugins/m4-documentation-hooks/styles.py
 src/llm_wiki_cli/extractors/__init__.py
 src/llm_wiki_cli/extractors/common.py
+src/llm_wiki_cli/extractors/fastapi_contracts.py
 src/llm_wiki_cli/extractors/go_extractor.py
 src/llm_wiki_cli/extractors/haskell_extractor.py
+src/llm_wiki_cli/extractors/python_contracts.py
 src/llm_wiki_cli/extractors/python_extractor.py
 src/llm_wiki_cli/extractors/rust_extractor.py
 src/llm_wiki_cli/extractors/ts_extractor.py
@@ -65,6 +67,7 @@ src/llm_wiki_cli/extractors/rust_scripts/src/main.rs
 src/llm_wiki_cli/extractors/ts_scripts/extract.js
 src/llm_wiki_cli/extractors/ts_scripts/package.json
 src/llm_wiki_cli/services/__init__.py
+src/llm_wiki_cli/services/api_contracts.py
 src/llm_wiki_cli/services/circuit_breaker.py
 src/llm_wiki_cli/services/contracts.py
 src/llm_wiki_cli/services/data_flow.py
@@ -122,10 +125,14 @@ src/llm_wiki_cli/skills/user-docs-author/SKILL.md
 src/llm_wiki_cli/skills/user-docs-author/reference.md
 src/llm_wiki_cli/skills/wiki-bootstrap/SKILL.md
 src/llm_wiki_cli/skills/wiki-bootstrap/reference.md
+src/llm_wiki_cli/skills/wiki-reference/SKILL.md
+src/llm_wiki_cli/skills/wiki-reference/reference.md
 src/llm_wiki_cli/skills/wiki-sync/SKILL.md
 src/llm_wiki_cli/skills/wiki-sync/reference.md
 tests/test_api.py
+tests/test_api_contracts.py
 tests/test_bootstrap.py
+tests/test_bootstrap_api_contracts.py
 tests/test_bump.py
 tests/test_ci_check.py
 tests/test_circuit_breaker.py
@@ -143,6 +150,7 @@ tests/test_documentation_queries.py
 tests/test_e2e.py
 tests/test_entrypoints.py
 tests/test_extract.py
+tests/test_extract_api_contracts.py
 tests/test_extractor_helpers.py
 tests/test_extractor_inventory_contracts.py
 tests/test_generate_prompt.py
@@ -152,6 +160,7 @@ tests/test_hook.py
 tests/test_imports.py
 tests/test_infrastructure_inventory.py
 tests/test_init.py
+tests/test_install.py
 tests/test_inventory_cache.py
 tests/test_io.py
 tests/test_lint.py
@@ -179,12 +188,15 @@ tests/test_site_export.py
 tests/test_skills.py
 tests/test_source_snapshot.py
 tests/test_status.py
+tests/test_surface_initialization.py
 tests/test_sync.py
+tests/test_sync_api_contracts.py
 tests/test_team.py
 tests/test_trigger.py
 tests/test_ts_extract.py
 tests/test_uninstall.py
 tests/test_upgrade.py
 tests/test_versioning.py
+tests/test_wiki_reference_skill.py
 tests/test_wiki_surface.py
 tests/test_wiki_surface_index.py

{agent_wiki_cli-1.2.0 → agent_wiki_cli-1.3.0}/src/agent_wiki_cli.egg-info/requires.txt

@@ -1,3 +1,4 @@
+PyYAML>=6
 
 [:python_version < "3.11"]
 tomli>=2

{agent_wiki_cli-1.2.0 → agent_wiki_cli-1.3.0}/src/llm_wiki_cli/api.py

@@ -383,7 +383,8 @@ def _wiki_page_counts(pages: list[dict[str, Any]]) -> dict[str, Any]:
     for page in pages:
         by_kind[str(page["kind"])] += 1
     architecture_pages = (
-        by_kind[wiki_surface.PageKind.DEPENDENCIES.value]
+        by_kind[wiki_surface.PageKind.API_CONTRACTS.value]
+        + by_kind[wiki_surface.PageKind.DEPENDENCIES.value]
         + by_kind[wiki_surface.PageKind.LOAD_ORDER.value]
     )
     return {