@thanbir-tamim/enterprise-project-intelligence-agent 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## 0.1.0 — Initial local build (unreleased)
+## 0.2.0
+
+- Hardened and fixed all 20 evaluation findings (F-01..F-20): planner 0-score -> insufficient-evidence and documented blocker taxonomy; honest YAML/CSV extraction; entropy-based secret detection with file/line records; XSS-safe Markdown renderer with ordered lists/blockquotes; auditor anchor/citation/contradiction checks + CLI; executable deck-JSON handoff; schema-validated presentation rules; single-line skill descriptions for cross-harness portability.
+- Added scripts: project-documentation-discovery/secrets.mjs, corporate-presentation-generator/outline-to-deck-json.mjs; software-reverse-engineering system-map schema.
+- Contradiction detector precision fix (suppresses templated/series false positives).
+- Added Performance evaluation section to the README (anonymized aggregates).
+- 42/42 tests; release-audit 0 findings on the published package.
+
+## 0.1.2
+
+- Rewrote README.md: added badges, an ASCII banner, a table of contents, and a detailed
+  per-skill section for all 10 skills (purpose, inputs, outputs, example links).
+- No functional changes to skills or scripts.
+
+## 0.1.1
+
+- Fixed stale README "Status" section (incorrectly said "unpublished" after the package was
+  published to npm).
+- No functional changes to skills or scripts.
+
+## 0.1.0 — Initial public release
 
 - Added 10 composable Agent Skills: `project-documentation-discovery`,
   `project-knowledge-assistant`, `software-reverse-engineering`,
@@ -18,5 +38,6 @@
   feasibility scoring (including the non-overridable blocker rule), presentation compliance
   checking, Markdown rendering, and release-audit secret detection.
 - Added toolkit documentation under `docs/`.
-- Not yet published to any package registry. See `docs/IMPLEMENTATION_REPORT.md` for status and
+- Not yet published to any package registry at the time this entry was written. See
+  `docs/IMPLEMENTATION_REPORT.md` for status and
   the release-preparation checklist.

package/README.md

@@ -1,54 +1,219 @@
-# Enterprise Project Intelligence & AI Integration Agent
+```
+ ███████╗██████╗ ██╗
+ ██╔════╝██╔══██╗██║
+ █████╗  ██████╔╝██║
+ ██╔══╝  ██╔══██╗██║
+ ███████╗██║  ██║██║
+ ╚══════╝╚═╝  ╚═╝╚═╝
+ Enterprise Project Intelligence & AI Integration Agent
+ ──────────────────────────────────────────────────────
+ Evidence-grounded reverse engineering + AI opportunity planning,
+ as a reusable, project-agnostic Agent Skills toolkit.
+```
+
+<p align="center">
+  <img src="assets/figures/hero-architecture.png" alt="Enterprise Project Intelligence Pipeline" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@thanbir-tamim/enterprise-project-intelligence-agent"><img src="https://img.shields.io/npm/v/@thanbir-tamim/enterprise-project-intelligence-agent?color=cb3837&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@thanbir-tamim/enterprise-project-intelligence-agent"><img src="https://img.shields.io/npm/dm/@thanbir-tamim/enterprise-project-intelligence-agent?color=cb3837" alt="npm downloads"></a>
+  <a href="https://github.com/ThanbirTamim/enterprise-project-intelligence/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white" alt="Node >= 18"></a>
+  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero required dependencies">
+  <img src="https://img.shields.io/badge/skills-10-blueviolet" alt="10 Agent Skills">
+  <img src="https://img.shields.io/badge/tests-23%2F23%20passing-success" alt="23/23 tests passing">
+</p>
+
+<p align="center"><strong>⭐ If this toolkit saves you a round of "where should we even put AI in this app?" meetings, consider starring the repo.</strong></p>
 
-A project-agnostic, organization-agnostic **Agent Skills toolkit** that helps an AI assistant:
+---
 
-1. Ingest and inventory a software project's documentation and (optionally) source code.
-2. Reconstruct architecture, workflows, APIs, and data model from the available evidence.
-3. Answer questions about the project with source citations.
-4. Discover, score, and plan **AI integration opportunities** — including for projects with *no*
-   existing AI — always comparing against the simplest non-AI alternative, and never letting a high
-   score override a critical security/privacy/legal blocker.
-5. Generate evidence-backed technical documentation and corporate presentations against
-   user-supplied (not hardcoded) style guidelines.
-6. Audit documentation quality, trace change impact, and generate onboarding/knowledge-transfer
-   material.
+## What is this?
 
-This repository ships **skills** (instructions for an AI coding agent), **reference scripts**
-(deterministic, dependency-free Node.js helpers), **templates**, and a **synthetic** worked example.
-It contains **no real organization's project data, branding, or proprietary guideline text**.
+A **project-agnostic, organization-agnostic Agent Skills toolkit** — a set of instructions, reference
+scripts, and templates that let an AI coding agent:
+
+> **Ingest → Reconstruct → Ask → Plan AI → Document → Present → Audit → Maintain**
+
+...for *any* software project you point it at, grounding every material claim in cited evidence
+instead of plausible-sounding guesses.
+
+It ships **zero required third-party dependencies**, works with **any AI agent that supports the
+Agent Skills convention** (a `SKILL.md` with YAML frontmatter per skill), and treats "should we even
+use AI here?" as a real question with a real non-AI alternative — not a foregone conclusion.
+
+```
+ docs/code  ──▶  project-documentation-discovery  ──▶  evidence-index.json
+                            │
+                            ▼
+                 software-reverse-engineering  ──▶  architecture + data model
+                            │
+          ┌─────────────────┼──────────────────────┐
+          ▼                 ▼                       ▼
+  project-knowledge-   enterprise-ai-        documentation-quality-
+     assistant         integration-planner        auditor
+   (cited Q&A)      (opportunities, scores,    (contradictions,
+                     roadmap, security)         stale docs, gaps)
+          │                 │                       │
+          └─────────────────┼───────────────────────┘
+                            ▼
+      technical-document-generator · corporate-presentation-generator
+                 (Markdown / HTML / decks, all cited)
+```
+
+<p align="center">
+  <img src="assets/figures/skills-interaction-map.png" alt="Skills Composition and Interaction Map" width="95%">
+</p>
+
+## Table of contents
+
+- [Why this exists](#why-this-exists)
+- [Quick start](#quick-start)
+- [The 10 skills, in detail](#the-10-skills-in-detail)
+- [Repository layout](#repository-layout)
+- [Confidentiality by construction](#confidentiality-by-construction)
+- [Testing & validation](#testing--validation)
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Status](#status)
+- [Contributing & license](#contributing--license)
 
 ## Why this exists
 
 Most "apply AI to my project" advice is generic. This toolkit instead:
 
-- Grounds every material claim in cited evidence from the user's own project corpus.
-- Treats "should we even use AI here?" as a real question with a real non-AI alternative, not a
-  foregone conclusion.
-- Separates deterministic checks (file inventory, schema validation, compliance rule-matching) from
-  AI-assisted judgment, so the parts that can be verified mechanically are verified mechanically.
-- Keeps private project data and public toolkit code in separate places by construction.
+- 🔎 **Grounds every material claim** in cited evidence pulled from *your* project's own corpus —
+  not from the model's general knowledge about "systems like this."
+- ⚖️ **Treats AI as a hypothesis, not a default.** Every proposed AI feature is compared against the
+  simplest viable non-AI alternative before it's recommended.
+- 🧮 **Separates deterministic checks from AI judgment.** Feasibility-score arithmetic, the
+  non-overridable security-blocker rule, presentation-rule matching, Markdown rendering, and secret
+  scanning are all plain, tested Node.js code — not left to a model to "probably get right."
+- 🔒 **Keeps private project data and public toolkit code structurally separate** — nothing you feed
+  it ends up in this repository, and a release-audit script scans for secrets/paths before anything
+  is ever published.
+- 🧩 **Composable, not monolithic.** Ten independent skills you can mix and match, each with its own
+  purpose, inputs, outputs, evidence rules, and anti-fabrication rules.
 
 ## Quick start
 
 ```bash
-# List the available skills
+# Clone it
+git clone https://github.com/ThanbirTamim/enterprise-project-intelligence.git
+cd enterprise-project-intelligence
+
+# Or install the published package
+npm install -g @thanbir-tamim/enterprise-project-intelligence-agent
+
+# See what's inside
 node scripts/cli.mjs list
 
-# Validate skill structure (frontmatter, required sections, referenced files exist)
+# Validate skill structure (frontmatter, required sections, referenced files all exist)
 node scripts/cli.mjs validate
 
-# Inventory a documentation corpus (reports counts; see the skill for persisted output)
+# Point it at a real documentation corpus (writes to a private directory, never into this repo)
 node scripts/cli.mjs inventory /path/to/your/project/docs --out ./.local-knowledge/my-project
 
-# Run the public-release confidentiality/secret audit over this repository
+# Run the full test suite
+npm test
+
+# Run the public-release confidentiality/secret audit
 node scripts/cli.mjs release-audit
 ```
 
-Then point your AI coding agent (one that supports the Agent Skills convention — each skill is a
-`SKILL.md` with YAML frontmatter) at the `skills/` directory, or install individual skill folders
-into your agent's skills directory. Start with `project-documentation-discovery`, then
+Then point your AI coding agent at the `skills/` directory (or copy individual `skills/<name>/`
+folders into your agent's own skills directory). Start with `project-documentation-discovery`, then
 `software-reverse-engineering` and/or `project-knowledge-assistant`, then
-`enterprise-ai-integration-planner`.
+`enterprise-ai-integration-planner`. Full walkthrough in [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md).
+
+---
+
+## The 10 skills, in detail
+
+Each skill is a self-contained `SKILL.md` (purpose, required inputs, execution procedure, expected
+outputs, evidence requirements, anti-fabrication rules, error handling, security considerations) plus
+`references/` material and, where determinism matters, a tested `scripts/*.mjs` helper.
+
+### 1. 📂 `project-documentation-discovery`
+**The entry point for any new project.** Walks a documentation/code corpus, classifies every file by
+format, extracts headings/tables/structure for what it can genuinely parse (Markdown, text, JSON,
+YAML, CSV, HTML), and **honestly** flags what it can't (DOCX/PPTX/PDF/Keynote/Pages) instead of
+silently skipping or falsely claiming success.
+- **Inputs**: a corpus path, optional project profile (confidentiality level, excluded paths).
+- **Outputs**: `inventory.json`, `evidence-index.json`, `INVENTORY_SUMMARY.md`.
+- **Reference script**: [`scripts/inventory.mjs`](skills/project-documentation-discovery/scripts/inventory.mjs) — zero dependencies, redacts secret-shaped strings before indexing.
+
+### 2. 💬 `project-knowledge-assistant`
+Answers questions about the target project **strictly from the evidence index** — every material
+claim is cited with a `source_location`, every inference is labeled as an inference, and
+contradictions between sources are surfaced, never silently resolved.
+- **Inputs**: evidence index + the user's question.
+- **Outputs**: a cited answer, confidence labels (`documented` / `verified-in-code` / `inferred` /
+  `unverified-claim` / `superseded`), or an explicit "not found in the evidence."
+
+### 3. 🏗️ `software-reverse-engineering`
+Reconstructs architecture, modules, APIs, data model, and workflows from whatever evidence is
+available — reconciling documentation against actual code when both exist, and clearly separating
+`verified-in-code` facts from `documented-only` claims from honest inferences.
+- **Outputs**: module map, API/route inventory, data model summary, workflow reconstructions,
+  documentation-vs-code discrepancy list, and an explicit "could not verify" section.
+
+### 4. 🤖 `enterprise-ai-integration-planner` — the flagship skill
+Discovers, scores, and plans **AI integration opportunities for any project — including ones with
+zero existing AI.** Every proposal is compared against the simplest non-AI alternative first. Scoring
+is an eight-dimension, published weighting formula with a **non-overridable blocker rule**: a critical
+security/privacy/legal/authorization blocker forces `blocked`/`rework-required` *no matter how high
+the weighted score is* — enforced in code, not just prose, and covered by automated tests.
+
+<p align="center">
+  <img src="assets/figures/feasibility-scoring-engine.png" alt="Feasibility Scoring and Blocker Override Engine" width="90%">
+</p>
+
+- **Reference script**: [`scripts/score-opportunity.mjs`](skills/enterprise-ai-integration-planner/scripts/score-opportunity.mjs) — pure function, fully reproducible.
+- **Generates**: `AI_INTEGRATION_STRATEGY.md`, `AI_OPPORTUNITY_MATRIX.md`, `AI_FEASIBILITY_ASSESSMENT.md`,
+  `AI_REFERENCE_ARCHITECTURE.md`, `AI_SECURITY_AND_GOVERNANCE.md`, `AI_EVALUATION_FRAMEWORK.md`,
+  `AI_IMPLEMENTATION_ROADMAP.md`, `AI_PILOT_PROPOSAL.md`, `AI_INTEGRATION_FAQ.md`, a risk register,
+  and a pilot acceptance checklist.
+- **Try it**: [`examples/synthetic-inventory-system/ai-opportunity-matrix/`](examples/synthetic-inventory-system/ai-opportunity-matrix/AI_OPPORTUNITY_MATRIX.md) — a fully worked, fictional example, including a reproducible score showing the blocker rule in action.
+
+### 5. 🖼️ `corporate-presentation-generator`
+Builds evidence-backed slide decks from project evidence, against **your** supplied corporate
+guidelines (or a neutral, original default style guide — never a real company's proprietary rules).
+Every factual slide is cited or explicitly labeled illustrative.
+
+### 6. ✅ `presentation-compliance-validator`
+Converts configurable presentation guidelines into structured rules and validates a deck against
+them — **specific, itemized violations and corrective actions**, never a vague aggregate score.
+Honestly reports `not-checkable-from-this-format` rather than guessing a pass when the deck
+representation doesn't expose a property (e.g., no color/font metadata).
+- **Reference script**: [`scripts/validate-deck.mjs`](skills/presentation-compliance-validator/scripts/validate-deck.mjs).
+
+### 7. 📄 `technical-document-generator`
+Renders structured findings from the other skills into consistent Markdown/HTML artifacts (DOCX/PPTX
+only through a verified exporter — never claimed without one), preserving every citation attached to
+the source finding.
+- **Reference script**: [`scripts/render-markdown-to-html.mjs`](skills/technical-document-generator/scripts/render-markdown-to-html.mjs) — a dependency-free Markdown → HTML renderer.
+
+### 8. 🩺 `documentation-quality-auditor`
+Finds contradictions, stale documents, broken internal references, missing required sections, and
+unsupported claims across a documentation corpus — always reporting both sides of a contradiction,
+never auto-resolving.
+
+### 9. 🌊 `software-change-impact-analyzer`
+Traces the likely effects of a proposed change across modules, APIs, workflows, tests, data entities,
+and documentation — scoping confidence honestly (first-order impacts vs. lower-confidence second-order
+effects) rather than implying full coverage.
+
+### 10. 🎓 `engineering-knowledge-transfer`
+Generates onboarding guides, operational runbooks, handover documents, and troubleshooting guides
+from the same evidence base — with explicit `TODO: confirm with current operator` markers instead of
+fabricated procedures when the evidence doesn't cover something.
+
+> 📑 One-page table version: [`docs/SKILL_CATALOG.md`](docs/SKILL_CATALOG.md). Live version straight
+> from each skill's frontmatter: `node scripts/cli.mjs list`.
+
+---
 
 ## Repository layout
 
@@ -62,29 +227,120 @@ tests/                          Automated tests (node:test) using synthetic fixt
 evaluations/                    Evaluation guide placeholders for AI-assisted review quality
 ```
 
-See `docs/SKILL_CATALOG.md` for a one-page summary of every skill, and
-`docs/IMPLEMENTATION_REPORT.md` for the full implementation report.
-
 ## Confidentiality by construction
 
-This toolkit was developed using private reference material to understand real-world requirements,
-but:
-
 - No internal project name, organization name, proprietary feature, internal URL, file path, or
   employee name appears anywhere in this repository.
-- All examples use a fictional "synthetic inventory management platform."
-- The default presentation style guide is original, neutral, placeholder-branded content — not any
-  company's proprietary guideline.
-- `scripts/release-audit.mjs` scans for secret-shaped values, local filesystem paths, and
-  configurable private terms before any release, reporting file/line/category **without printing
-  the matched value**. This is a safeguard, not a guarantee — human review is still required before
-  publishing anything derived from a real project.
+- All examples use a fictional **"Synthetic Inventory Platform."**
+- The default presentation style guide is original, neutral, placeholder-branded content.
+- [`scripts/release-audit.mjs`](scripts/release-audit.mjs) scans for secret-shaped values, local
+  filesystem paths, and configurable private terms before any release — reporting **file, line, and
+  category only, never the matched value.** Safeguard, not a guarantee; human review is still
+  required.
+
+## Testing & validation
+
+```bash
+npm test              # 42/42 passing — node:test, zero test-framework dependency
+npm run validate       # structural validation of every skill
+npm run release-audit  # secret/path scan before any release
+npm run pack:dry-run   # inspect exactly what would be published
+```
+
+See [`docs/TESTING_STRATEGY.md`](docs/TESTING_STRATEGY.md) for what's covered automatically versus
+what needs human/AI-assisted review ([`docs/EVALUATION_GUIDE.md`](docs/EVALUATION_GUIDE.md)).
+
+## Performance evaluation
+
+The toolkit ships with a reproducible evaluation harness (`evaluations/`). Results below are from
+that harness; project-specific raw outputs are never committed (see the confidentiality note).
+
+### Deterministic correctness (synthetic fixtures)
+
+| Check | Result |
+|---|---|
+| Deterministic functional tests (`evaluations/harness/run-deterministic-evals.mjs`) | **84 / 84 pass** |
+| Repository unit/regression tests (`npm test`) | **42 / 42 pass** |
+| Skill-structure validation | **0 errors** across all 10 skills |
+| Release audit on the published package | **0 findings** |
+
+### With-skill vs. without-skill (A/B, synthetic benchmark)
+
+Same model, same inputs, graded against rubrics fixed before the runs
+(`evaluations/datasets/`):
+
+| | Without skill | With skill |
+|---|:--:|:--:|
+| Rubric score | 39 / 43 (91%) | **43 / 43 (100%)** |
+| Regressions | — | **0** |
+
+The skill arm's gains show up as consistent citations, confidence labels, non-AI-first comparisons,
+confidentiality handling, and TODO markers, at a token-cost premium. Real activation (an agent
+loading the right skill for a request) scored **22 / 22** across 12 positive and 10 negative prompts.
+
+### Scale & robustness (real-world codebase)
+
+Validated against a real-world **Vue + Laravel enterprise codebase** (~5,900 non-vendor source files
+across PHP/TypeScript/Vue, ~1.9 GB) to confirm the deterministic skills hold at scale. Aggregate,
+anonymized metrics only — no project data is included in this package:
+
+| Metric | Result |
+|---|---|
+| Files inventoried by `project-documentation-discovery` | 5,904 in **2.07 s**, peak **267 MB** RAM |
+| Unsupported/binary formats | correctly flagged (not silently skipped) |
+| Secret-like values | redacted and recorded by file/line, values never emitted |
+| `documentation-quality-auditor` precision fix | contradiction false-positives on templated/series content reduced from thousands to **0**, with real cross-document contradictions still detected |
+
+A with-skill vs. without-skill A/B on that codebase's functional documentation (4 queries x 2 arms,
+run strictly sequentially) scored **71% -> 100%** rubric compliance: without the skill the model
+mislabeled documented-only facts as verified, skipped reproducibility/limits disclosure, and applied
+no transparent feasibility scoring; the skill arm corrected all of these with no regressions.
+(Per the confidentiality policy, the project's queries and responses are kept private; only these
+aggregate numbers are published.)
+
+> Per-skill 0–5 scores and methodology: [`evaluations/SKILLS_EVALUATION_REPORT.md`](evaluations/SKILLS_EVALUATION_REPORT.md)
+> (overall **4.76 / 5**, every skill ≥ 4.5). The harness is memory-bounded; run any LLM-based A/B in
+> small sequential batches, not all at once.
+
+
+## Installation
+
+Full instructions: [`docs/INSTALLATION.md`](docs/INSTALLATION.md) · [`docs/QUICK_START.md`](docs/QUICK_START.md)
+
+```bash
+npm install -g @thanbir-tamim/enterprise-project-intelligence-agent
+epi-agent list
+```
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md) | End-to-end workflow across all 10 skills |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Design principles, component map |
+| [`docs/SKILL_CATALOG.md`](docs/SKILL_CATALOG.md) | One-page skill reference table |
+| [`docs/KNOWLEDGE_MODEL.md`](docs/KNOWLEDGE_MODEL.md) · [`docs/EVIDENCE_AND_PROVENANCE.md`](docs/EVIDENCE_AND_PROVENANCE.md) | How evidence/citations work |
+| [`docs/SUPPORTED_FORMATS.md`](docs/SUPPORTED_FORMATS.md) | What's actually tested vs. aspirational |
+| [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md) | Threat model + safeguards |
+| [`docs/IMPLEMENTATION_REPORT.md`](docs/IMPLEMENTATION_REPORT.md) | Full build report: what was implemented, tested, verified |
+| [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) | Common issues and fixes |
 
 ## Status
 
-This is a local, unpublished package (see `docs/IMPLEMENTATION_REPORT.md`). Nothing in this
-repository is published or released automatically.
+Published on npm as
+[`@thanbir-tamim/enterprise-project-intelligence-agent`](https://www.npmjs.com/package/@thanbir-tamim/enterprise-project-intelligence-agent).
+See [`CHANGELOG.md`](CHANGELOG.md) for release history and
+[`docs/IMPLEMENTATION_REPORT.md`](docs/IMPLEMENTATION_REPORT.md) for the detailed build/verification
+report. Future releases are published deliberately, never automatically, following the checklist in
+[`docs/INSTALLATION.md`](docs/INSTALLATION.md).
+
+## Contributing & license
+
+Contributions welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) (ground rule #1: no confidential
+content, ever) and [`SECURITY.md`](SECURITY.md) for vulnerability reporting.
+
+Licensed under [Apache-2.0](LICENSE).
 
-## License
+---
 
-Apache-2.0 — see `LICENSE`.
+<p align="center"><em>Built for engineers who want an honest answer to "where should AI go in this system?" — including when the honest answer is "nowhere, yet."</em></p>

package/docs/INSTALLATION.md

@@ -7,10 +7,10 @@
 - An AI coding agent that supports the Agent Skills convention (a `SKILL.md` file with YAML
   frontmatter per skill directory), to actually use the skills as agent instructions.
 
-## Option A — clone and use locally (recommended while unpublished)
+## Option A — clone and use locally
 
 ```bash
-git clone <this-repo-url>
+git clone https://github.com/ThanbirTamim/enterprise-project-intelligence.git
 cd enterprise-project-intelligence
 node scripts/cli.mjs list
 ```
@@ -18,16 +18,16 @@ node scripts/cli.mjs list
 Point your agent's skills directory at this repo's `skills/` folder, or copy individual
 `skills/<name>/` directories into your agent's own skills directory.
 
-## Option B — install as an npm package (once published)
+## Option B — install as an npm package
 
-This package is **not currently published**. If/when it is published under
-`@thanbir-tamim/enterprise-project-intelligence-agent`, install with:
+Published at
+[`@thanbir-tamim/enterprise-project-intelligence-agent`](https://www.npmjs.com/package/@thanbir-tamim/enterprise-project-intelligence-agent):
 
 ```bash
 npm install -g @thanbir-tamim/enterprise-project-intelligence-agent
 ```
 
-Before any real publication, run:
+Before any new release, run:
 
 ```bash
 npm run validate

package/docs/SUPPORTED_FORMATS.md

@@ -10,10 +10,10 @@ rationale per format.
 | Markdown | Verified |
 | Plain text | Verified |
 | JSON | Verified |
-| YAML | Verified (subset) |
-| CSV | Verified |
-| HTML (headings/tables) | Verified (subset — no CSS/JS rendering) |
-| Source code / config files | Verified (treated as text) |
+| YAML | Verified (syntax check only; `extracted-partial`) |
+| CSV | Verified (quote-aware) |
+| HTML (headings/tables) | Verified (subset; always `extracted-partial`) |
+| Source code / config files | Verified (treated as text; secret-scanned) |
 | Images / screenshots | Catalogued only (no OCR); flagged for manual review |
 | DOCX | Unsupported in the bundled reference implementation (requires an optional dependency) |
 | PPTX | Unsupported in the bundled reference implementation (requires an optional dependency) |

package/examples/synthetic-inventory-system/ai-opportunity-matrix/AI_OPPORTUNITY_MATRIX.md

@@ -9,8 +9,8 @@
 | Field | Value |
 |---|---|
 | Target module / workflow | Receiving |
-| Current behavior | Associate manually re-keys packing-slip quantities into the Receiving screen [source: receiving-workflow.md#2-steps]. |
-| User problem | Manual re-keying causes typos and stock mismatches [source: overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
+| Current behavior | Associate manually re-keys packing-slip quantities into the Receiving screen [source: source-docs/receiving-workflow.md#2-steps]. |
+| User problem | Manual re-keying causes typos and stock mismatches [source: source-docs/overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
 | Proposed capability | Extract line-item quantities from a scanned/photographed packing slip and pre-fill the Receiving form for associate confirmation. |
 | Proposed integration point | New "suggested receipt" step before the existing manual-entry step; associate still confirms/edits before submission. |
 | Required data | Scanned packing slip images; existing PO line items for cross-checking. |
@@ -36,7 +36,7 @@ node skills/enterprise-ai-integration-planner/scripts/score-opportunity.mjs \
 | Field | Value |
 |---|---|
 | Target module / workflow | Reporting |
-| Current behavior | A staff member reads a weekly CSV report to decide on reorders [source: overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
+| Current behavior | A staff member reads a weekly CSV report to decide on reorders [source: source-docs/overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
 | User problem | Delay between stock dropping below reorder point and a human noticing it. |
 | Proposed capability | Deterministic rule: alert when `current_quantity < reorder_point` (see `sample-catalog.csv`). |
 | Non-AI alternative | **This is the recommended solution.** A scheduled job comparing quantity to reorder point is a complete, lower-risk fit — no AI technique is needed here. |
@@ -49,7 +49,7 @@ node skills/enterprise-ai-integration-planner/scripts/score-opportunity.mjs \
 | Field | Value |
 |---|---|
 | Target module / workflow | Purchase Orders |
-| Current behavior | Support staff search old email threads to answer "why was this PO changed" [source: overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
+| Current behavior | Support staff search old email threads to answer "why was this PO changed" [source: source-docs/overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
 | Proposed capability | A RAG-style assistant over structured PO change logs (once such logs exist) producing cited explanations. |
 | Non-AI alternative | First, simply start recording structured change history (who/when/what/why) on every PO edit — this alone may resolve most of the problem without any AI component. |
 | AI technique | Retrieval-augmented generation, recommended only after structured change history exists. |

package/examples/synthetic-inventory-system/generated-docs/INVENTORY_SUMMARY.md

@@ -0,0 +1,17 @@
+# Inventory summary
+
+Corpus: `source-docs`
+Total files: 3
+
+## By status
+- extracted-full: 3
+
+## By type
+- markdown: 2
+- csv: 1
+
+## Files needing manual/visual review
+- none
+
+## Redacted secret-like values
+- none

package/examples/synthetic-inventory-system/generated-docs/evidence-index.json

@@ -0,0 +1,78 @@
+[
+  {
+    "source_path": "overview.md",
+    "source_location": "overview.md#synthetic-inventory-platform--overview",
+    "heading_path": "Synthetic Inventory Platform — Overview",
+    "evidence_type": "text",
+    "level": 1
+  },
+  {
+    "source_path": "overview.md",
+    "source_location": "overview.md#1-purpose",
+    "heading_path": "1. Purpose",
+    "evidence_type": "text",
+    "level": 2
+  },
+  {
+    "source_path": "overview.md",
+    "source_location": "overview.md#2-modules",
+    "heading_path": "2. Modules",
+    "evidence_type": "text",
+    "level": 2
+  },
+  {
+    "source_path": "overview.md",
+    "source_location": "overview.md#3-known-pain-points-fictional-for-demonstration-only",
+    "heading_path": "3. Known pain points (fictional, for demonstration only)",
+    "evidence_type": "text",
+    "level": 2
+  },
+  {
+    "source_path": "receiving-workflow.md",
+    "source_location": "receiving-workflow.md#receiving-workflow-fictional",
+    "heading_path": "Receiving Workflow (fictional)",
+    "evidence_type": "text",
+    "level": 1
+  },
+  {
+    "source_path": "receiving-workflow.md",
+    "source_location": "receiving-workflow.md#1-trigger",
+    "heading_path": "1. Trigger",
+    "evidence_type": "text",
+    "level": 2
+  },
+  {
+    "source_path": "receiving-workflow.md",
+    "source_location": "receiving-workflow.md#2-steps",
+    "heading_path": "2. Steps",
+    "evidence_type": "text",
+    "level": 2
+  },
+  {
+    "source_path": "receiving-workflow.md",
+    "source_location": "receiving-workflow.md#3-business-rules",
+    "heading_path": "3. Business rules",
+    "evidence_type": "text",
+    "level": 2
+  },
+  {
+    "source_path": "receiving-workflow.md",
+    "source_location": "receiving-workflow.md#4-known-limitation",
+    "heading_path": "4. Known limitation",
+    "evidence_type": "text",
+    "level": 2
+  },
+  {
+    "source_path": "sample-catalog.csv",
+    "source_location": "sample-catalog.csv#table",
+    "heading_path": "table (4 rows, columns: item_sku|description|category|reorder_point|current_quantity)",
+    "evidence_type": "table",
+    "columns": [
+      "item_sku",
+      "description",
+      "category",
+      "reorder_point",
+      "current_quantity"
+    ]
+  }
+]

package/examples/synthetic-inventory-system/generated-docs/inventory.json

@@ -0,0 +1,26 @@
+[
+  {
+    "path": "overview.md",
+    "type": "markdown",
+    "title": "Synthetic Inventory Platform — Overview",
+    "status": "extracted-full",
+    "hash": "d69cab662c1414eaab7216212eb74c36edfc37df62962e5206c30ac64f931158",
+    "warnings": []
+  },
+  {
+    "path": "receiving-workflow.md",
+    "type": "markdown",
+    "title": "Receiving Workflow (fictional)",
+    "status": "extracted-full",
+    "hash": "b50e0bf4cfbbec5a26ba3c747444466b8d7fe3ea47e2b3df434e6b2fe4589805",
+    "warnings": []
+  },
+  {
+    "path": "sample-catalog.csv",
+    "type": "csv",
+    "title": "sample-catalog.csv",
+    "status": "extracted-full",
+    "hash": "73183970de5e9582dabb645c9508c6c5064f8f11af36f9ba47245d1fc26a4762",
+    "warnings": []
+  }
+]