ProDocs 1.2: evidence-backed automatic adoption

.prodocs/integrations/AGENTS.md

@@ -2,8 +2,9 @@
 
 Before changing code:
 
-1. Run `prodocs context --path <area> --json` to load the local architecture context.
-2. Read `docs/prodocs/SYSTEM_OVERVIEW.md` for system-level constraints.
+1. If `prodocs doctor` reports incomplete onboarding, run `prodocs adopt` and review its cited proposal.
+2. Run `prodocs context --path <area> --json` to load the local architecture context.
+3. Read `docs/prodocs/SYSTEM_OVERVIEW.md` for system-level constraints.
 
 After changing code:
 

.prodocs/integrations/CLAUDE.md

@@ -1,5 +1,6 @@
 # ProDocs integration
 
+Use `prodocs adopt --json` to propose cited onboarding when readiness is incomplete.
 Use `prodocs context --path <area> --json` before editing unfamiliar code.
 After source changes, run `prodocs sync` and `prodocs check`.
 Treat `docs/prodocs/knowledge.json` as the machine-readable codebase map.

.prodocs/integrations/codex.md

@@ -1,5 +1,6 @@
 # ProDocs for Codex
 
+Use the read-only `prodocs_adopt` MCP tool to draft missing onboarding evidence.
 Run `prodocs context --path <area> --task "<goal>" --json` before editing.
 Use the local MCP server with `prodocs mcp` for bounded graph queries.
 After changes, run `prodocs impact --base <ref>`, `prodocs policy`,

.prodocs/integrations/opencode.md

@@ -1,5 +1,6 @@
 # ProDocs integration
 
+Use `prodocs adopt --json` to research incomplete onboarding before asking for manual documentation.
 Load scoped context with `prodocs context --path <area> --json`.
 Refresh generated evidence with `prodocs sync` after code changes.
 Run `prodocs check` before completing a task.

CHANGELOG.md

@@ -6,6 +6,34 @@ All notable changes to ProDocs are documented here. The project follows
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-08-09
+
+### Added
+
+- added `prodocs adopt` to infer cited product identity, framework entrypoints,
+  GitHub ownership, and policy-backed starter product knowledge;
+- added the read-only `prodocs_adopt` MCP tool for agent-led repository
+  onboarding;
+- published a versioned adoption-proposal JSON Schema and package API;
+- added automatic post-apply integration generation, documentation sync,
+  readiness diagnostics, and policy evaluation.
+
+### Changed
+
+- readiness remediation now directs adopters to automatic cited proposals
+  instead of requiring blank-field authorship;
+- agent integration recipes now research incomplete onboarding before asking
+  maintainers to write documentation manually.
+
+### Security
+
+- adoption approvals are bound to exact proposal content, source evidence, and
+  configuration state;
+- adoption writes are preflighted, repository-contained, schema-validated, and
+  limited to configuration, CODEOWNERS, and configured authored knowledge;
+- structured repository strings containing instruction-injection signals are
+  excluded from automatic identity inference.
+
 ## [1.1.2] - 2026-08-09
 
 ### Added
@@ -162,7 +190,8 @@ All notable changes to ProDocs are documented here. The project follows
 - Project-root containment for configured sources and generated output.
 - Versioned JSON Schemas for configuration and knowledge graph artifacts.
 
-[Unreleased]: https://github.com/boyeesu/prodocs/compare/v1.1.2...HEAD
+[Unreleased]: https://github.com/boyeesu/prodocs/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/boyeesu/prodocs/compare/v1.1.2...v1.2.0
 [1.1.2]: https://github.com/boyeesu/prodocs/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/boyeesu/prodocs/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/boyeesu/prodocs/compare/v1.0.0...v1.1.0

README.md

@@ -60,11 +60,29 @@ npm install --global @danielesuga/prodocs
 
 cd /path/to/your/repository
 prodocs init
-prodocs sync
+prodocs adopt
+# Review the cited proposal, then run the exact apply command it prints.
 prodocs doctor
 prodocs status
 ```
 
+`prodocs adopt` does the onboarding research: it infers structured product
+identity, framework entrypoints, likely GitHub ownership, and starter product
+knowledge with confidence and evidence citations. It writes a content-bound
+proposal under `.prodocs`; no inferred intent is applied until the exact
+approval hash is supplied:
+
+```bash
+prodocs adopt --json
+prodocs adopt \
+  --apply .prodocs/adoption-proposal.json \
+  --approve <approvalHash>
+```
+
+Application also creates any missing agent recipes, refreshes generated views,
+and returns doctor and policy results. Agents can request the same proposal
+without writes through the read-only `prodocs_adopt` MCP tool.
+
 Try the product without modifying an existing repository:
 
 ```bash
@@ -102,9 +120,9 @@ JSON remains the interoperability and debugging format.
 
 ## Authored knowledge
 
-Human intent lives in ordinary Markdown under `docs/knowledge`. ProDocs parses a
-strict, safe YAML front matter contract and never rewrites these files during
-`sync`.
+Reviewed intent lives in ordinary Markdown under `docs/knowledge`. ProDocs can
+draft the initial cited document through `adopt`; thereafter it parses a strict,
+safe YAML front matter contract and never rewrites these files during `sync`.
 
 ```markdown
 ---
@@ -200,6 +218,7 @@ prodocs mcp
 
 It implements the current MCP `2025-11-25` stdio protocol with read-only tools:
 
+- `prodocs_adopt`;
 - `prodocs_context`;
 - `prodocs_impact`;
 - `prodocs_policy`;
@@ -278,6 +297,7 @@ least 24 characters.
 | Command | Purpose |
 | --- | --- |
 | `prodocs init` | Create configuration and agent/MCP recipes |
+| `prodocs adopt` | Infer and propose cited identity, entrypoints, ownership, and starter knowledge |
 | `prodocs doctor` | Require warning-free identity, evidence, freshness, integrations, and knowledge readiness |
 | `prodocs tutorial` | Create a safe, complete getting-started project |
 | `prodocs sync` | Incrementally index evidence and render all views |

SECURITY.md

@@ -36,6 +36,9 @@ ProDocs treats repository contents and configuration as untrusted input:
   third-party plugin code;
 - proposal application requires an exact approval hash, rejects stale source
   hashes, and can only modify configured authored-documentation paths;
+- adoption proposals additionally bind configuration state, validate inferred
+  content, preflight all destinations, and restrict writes to configuration,
+  CODEOWNERS, and configured authored-knowledge paths;
 - runbook verification executes no shell and only supports built-in,
   time-bounded, output-bounded operations;
 - the collaboration API is loopback-only by default, requires a strong bearer

docs/ADOPTION.md

@@ -14,8 +14,24 @@ prodocs doctor
 prodocs context --path src/delivery.js --task "change retry behavior" --json
 ```
 
-In an existing repository, run `prodocs init`, review the configuration, then
-run `prodocs sync` and `prodocs doctor`.
+In an existing repository, let ProDocs research the initial configuration and
+knowledge instead of starting from blank fields:
+
+```sh
+prodocs init
+prodocs adopt
+```
+
+The proposal records confidence and evidence for product identity, framework
+entrypoints, repository ownership, and starter product knowledge. Review it,
+then run the exact content-bound apply command printed by ProDocs. Application
+creates missing agent recipes, synchronizes generated views, and returns both
+doctor and policy results. Repository source or configuration drift invalidates
+the proposal.
+
+Agents can retrieve the same proposal through `prodocs adopt --json` or the
+read-only `prodocs_adopt` MCP tool. Applying still requires the exact proposal
+hash, so repository-derived text never grants itself write authority.
 
 ## Local measurement
 

docs/ARCHITECTURE.md

@@ -13,6 +13,7 @@ flowchart LR
   Q --> C["CI drift and impact checks"]
   Q --> M["MCP and editor integrations"]
   L["Optional model providers"] --> P["Proposal engine"]
+  I --> P
   G --> P
   P --> R["Reviewable knowledge patches"]
   R --> H
@@ -79,11 +80,21 @@ LLMs are optional proposal generators over retrieved evidence. A proposal
 contains patch operations, citations, the evidence snapshot, confidence, and
 policy results. Applying it is a separate human- or policy-controlled action.
 
+Initial adoption uses the same boundary without an LLM. Bounded deterministic
+inference reads structured metadata, framework conventions, Git origin
+ownership, and indexed source evidence. It produces a content-bound proposal;
+source or configuration drift invalidates approval before any write. The apply
+path is repository-contained, preflights every operation, creates only missing
+ownership/knowledge files, and never replaces existing intent.
+
 ## Production layout
 
 ```text
 bin/prodocs.js             command entrypoint
 src/cli.js                 stable command surface
+src/adoption-inference.js  bounded identity, entrypoint, and owner inference
+src/adoption.js            content-bound adoption proposal and apply gate
+src/adoption-command.js    CLI orchestration and post-apply assurance
 src/scanner.js             deterministic evidence collection and graph
 src/collectors/            collector contract, registry, and implementations
 src/knowledge.js           strict authored-knowledge ingestion and evidence links
@@ -113,9 +124,9 @@ at runtime and include deterministic relevance, freshness, and size metadata.
 - backwards-compatibility policy;
 - third-party conformance fixtures.
 
-The graph and context packet use schema version 2. Impact, proposal, collector,
-plugin, policy, runbook-plan, and evaluation outputs have independent versioned
-contracts.
+The graph and context packet use schema version 2. Adoption, impact, proposal,
+collector, plugin, policy, runbook-plan, and evaluation outputs have independent
+versioned contracts.
 
 ## Security and trust
 

docs/MATURITY.md

@@ -1,7 +1,7 @@
 # Code maturity assessment
 
 Assessment date: 2026-08-02
-Target: ProDocs `1.1.2`, Node.js CLI and JavaScript library
+Target: ProDocs `1.2.0`, Node.js CLI and JavaScript library
 
 ## Executive summary
 

docs/PRODUCT_VISION.md

@@ -66,8 +66,8 @@ ProDocs separates four concepts that conventional documentation mixes together:
 2. **Claims** — assertions such as “the API retries failed deliveries three
    times.” A claim records supporting evidence, confidence, scope, and freshness.
 3. **Intent** — product goals, architectural decisions, invariants, policies,
-   tradeoffs, and operational expectations. Intent is explicitly authored and
-   reviewed by people.
+   tradeoffs, and operational expectations. ProDocs can infer a cited initial
+   draft; intent becomes authoritative only through content-bound approval.
 4. **Views** — system overviews, onboarding guides, product explanations,
    runbooks, diagrams, PR impact reports, and agent context packets.
 

docs/ROADMAP.md

@@ -156,3 +156,28 @@ New roadmap items require adopter evidence rather than speculative scope. The
 candidate themes are deeper language semantics, additional renderer/provider
 adapters, and larger monorepo performance, but each must begin with a
 reproducible adopter fixture and a measurable success threshold.
+
+## Release 1.2 — evidence-backed automatic adoption
+
+Status: **complete**.
+
+- deterministic `prodocs adopt` identity, framework-entrypoint, and GitHub
+  ownership inference;
+- cited starter product knowledge that covers inferred public surfaces;
+- content-bound proposals invalidated by source, configuration, or proposal
+  drift;
+- repository-contained application with existing-intent preservation;
+- automatic integration generation, view synchronization, doctor diagnostics,
+  and policy evaluation after apply;
+- read-only `prodocs_adopt` MCP support for Codex, Claude Code, OpenCode, and
+  other MCP clients;
+- public adoption-proposal JSON Schema and package API.
+
+Exit evidence:
+
+- a blank Kourti Tech onboarding advances from four readiness warnings to
+  12/12 passing checks without manually authored product text;
+- inferred product identity cites structured site metadata, 20 Next.js
+  boundaries are covered, and all 46 indexed files receive ownership evidence;
+- tampered, stale, unapproved, malformed, and repository-escaping proposals
+  fail closed in automated tests.

docs/SUPPLY_CHAIN.md

@@ -5,7 +5,7 @@
 ## Metadata
 
 - **Scan Date**: 2026-08-09 14:31 WAT
-- **Project**: ProDocs 1.1.2
+- **Project**: ProDocs 1.2.0
 - **Repositories Scanned**: 3 direct dependency repositories
 - **Total Dependencies**: 6 production packages excluding ProDocs
 - **Scan Duration**: approximately 2 minutes

docs/TROUBLESHOOTING.md

@@ -6,6 +6,14 @@ knowledge health without sending data anywhere. `ready: true` means there are
 no errors or warnings; incomplete product identity, entrypoints, ownership,
 relationships, or authored knowledge keeps the project explicitly not ready.
 
+## Onboarding fields are empty
+
+Run `prodocs adopt`. It inspects bounded structured metadata, framework file
+conventions, the Git origin, and indexed evidence to create a cited proposal.
+Review the proposal and run the exact `adopt --apply ... --approve ...` command
+it prints. ProDocs then synchronizes views and reports doctor and policy status.
+It never silently overwrites existing identity, ownership, or knowledge.
+
 ## `prodocs` is not found
 
 Install globally with `npm install --global @danielesuga/prodocs`, or use

docs/VALIDATION.md

@@ -39,6 +39,21 @@ The production gate runs all of the following:
 - compromised-release and provider-egress response procedures have a recorded
   tabletop walkthrough in `docs/TABLETOPS.md`.
 
+## 1.2 automatic-adoption gates
+
+- structured site metadata produces high-confidence identity citations;
+- Next.js App Router pages, layouts, route handlers, and metadata endpoints are
+  inferred as public entrypoints;
+- GitHub origin ownership produces a bounded CODEOWNERS proposal;
+- starter product knowledge cites every inferred public surface and passes
+  documentation policy after apply;
+- exact proposal, source, configuration, and inference-evidence hashes are
+  required before writes;
+- stale, tampered, unapproved, malformed, and symbolic-link-escaping proposals
+  fail before any operation is applied;
+- Kourti Tech moves from 8 passes and 4 warnings to 12 passes and no warnings,
+  with 20 entrypoints, 46/46 owned files, and supported starter knowledge.
+
 CI repeats compatible gates across Node.js 20, 22, and 24, with Linux, macOS,
 and Windows coverage. Pull requests also generate a machine-readable impact
 report before merge.

docs/knowledge/features/automatic-adoption.md

@@ -0,0 +1,28 @@
+---
+kind: feature
+id: automatic-adoption
+title: Evidence-backed automatic repository adoption
+status: active
+audiences:
+  - product
+  - technical
+  - security
+  - coding-agents
+evidence:
+  - src/adoption-inference.js#inferAdoption
+  - src/adoption.js#createAdoptionProposal
+  - src/adoption.js#applyAdoptionProposal
+  - src/adoption-command.js#runAdoptionCommand
+  - src/mcp.js#handleMcpRequest
+affects:
+  - src/adoption-inference.js
+  - src/adoption.js
+  - src/adoption-command.js
+  - src/doctor.js
+  - src/mcp.js
+customerImpact: Teams receive a cited, policy-complete onboarding draft instead of manually filling blank product, entrypoint, ownership, and knowledge fields.
+---
+ProDocs deterministically infers structured identity, framework boundaries, and
+repository ownership, then drafts starter product knowledge backed by indexed
+source evidence. The proposal is read-only until its exact hash is approved;
+source, configuration, inference evidence, or proposal drift invalidates it.