# Webdev Agent OS v5 — Web Intelligence Platform

## Purpose

The Web Intelligence Platform turns completed web work into reusable institutional intelligence. It prevents every project from starting at zero by preserving components, conversion patterns, repairs, deployments, architecture decisions, industry insights, checklists, and lessons with evidence and outcome history.

The platform is not a free-form note pile. Every record has a type, evidence level, confidence score, source, tags, applicable architectures and industries, usage metrics, and feedback history.

## Intelligence record types

| Type | Purpose |
|---|---|
| `component` | Reusable interface or interaction system |
| `conversion-pattern` | A pattern that improves task completion or business results |
| `repair-pattern` | A repeatable defect-to-fix method |
| `deployment-pattern` | Hosting, process, monitoring, recovery, or release knowledge |
| `architecture-decision` | A technology or system-boundary decision and its reasoning |
| `industry-insight` | Domain-specific workflow, trust, qualification, or content knowledge |
| `checklist` | A repeatable verification or release contract |
| `lesson` | A generalized finding that should influence future work |

The formal record contract is in `config/intelligence-record.schema.json`.

## Evidence model

The evidence model prevents guesses from becoming false institutional truth.

- **Hypothesis** — plausible but not yet observed or verified.
- **Observed** — found in a project, inspection, interview, or operational event.
- **Validated** — verified through testing, a successful repair, or a completed project outcome.
- **Proven** — repeatedly reused successfully with outcome evidence.

Confidence is stored separately from evidence level. Outcome feedback adjusts confidence over time. A failed reuse is retained and lowers confidence rather than being hidden.

## Included seed intelligence

v5 ships with 46 records across all eight record types, including:

- Outcome-first hero and progressive intake components
- Industry-specific proof and qualification patterns
- Accessibility, route, metadata, responsive, and false-success repairs
- IIS ARR, NSSM, health/readiness, environment, rollback, and smoke-test deployment patterns
- Static, Express, React, and operations-dashboard architecture decisions
- Roofing, trucking, AI voice-agent, and local-service insights
- Production form, Windows deployment, responsive evidence, and autonomous-change checklists
- Governance lessons for placeholder data, workflow testing, confidence, and human judgment

The immutable starter set is `library/intelligence-seed.json`. The working library is `library/intelligence-store.json`.

## Search and ranking

Search ranks records using:

1. Exact title and tag matches
2. Token matches across title, tags, summary, problem, solution, implementation, industry, architecture, and quality categories
3. Project-context matches
4. Evidence level
5. Confidence
6. Recorded use, success rate, and average score improvement

Normal search excludes deprecated records. Filters are available for type, evidence, architecture, and industry.

## Project-aware recommendation

The recommendation engine combines:

- Project name and industry
- Primary audience and user job
- Business outcome and success event
- Architecture preset
- Required features and integrations
- Hosting target
- Current inspection issues

It returns a diversified set of components, patterns, decisions, checklists, and lessons with a reason for each recommendation.

## Artifact ingestion

The platform can convert existing Webdev Agent artifacts into normalized intelligence:

### Project manifest

Produces an architecture-decision record and, when applicable, a deployment-pattern record.

### Inspection report

Groups repeated findings by rule or code and creates observed repair or lesson records with route evidence and recommendations.

### Verified repair plan

Creates repair-pattern records from staged operations. Verified improvements can enter at validated evidence with measured score delta.

### Intelligence store

Imports records from another Web Intelligence library while deduplicating fingerprints.

Equivalent records merge instead of multiplying. The richer fields, tags, source evidence, and stronger evidence state are retained.

## Outcome feedback

A record can receive `success`, `failure`, or `neutral` feedback with:

- Project name
- Score delta
- Notes
- Timestamp

The platform updates use count, success/failure totals, average score delta, last-used time, version, and confidence. Feedback history is capped to the 50 most recent entries per record.

## Control Center workflow

1. Open **Web Intelligence**.
2. Search the library or select a quick query.
3. Complete Project Intake and select an architecture.
4. Generate project-aware recommendations.
5. Capture a new record manually when a reusable lesson emerges.
6. Ingest the current generated project, inspection report, or repair plan.
7. Mark reused records as useful or needing work.
8. Export the library for backup or transfer.

When opened through static hosting, search and recommendation remain available in read-only mode. Persistent capture, ingestion, and feedback require `npm run serve`.

## API

The local server binds to `127.0.0.1` by default.

| Method | Route | Purpose |
|---|---|---|
| `GET` | `/api/intelligence/stats` | Library counts, evidence, confidence, types, and tags |
| `GET` | `/api/intelligence/search` | Ranked search with query and filters |
| `GET` | `/api/intelligence/export` | Full working store |
| `POST` | `/api/intelligence/recommend` | Project-aware recommendations |
| `POST` | `/api/intelligence/records` | Create or merge a record |
| `POST` | `/api/intelligence/ingest` | Ingest a manifest, inspection, repair plan, or store |
| `POST` | `/api/intelligence/feedback` | Record reuse outcome and update confidence |

The store path can be overridden for isolated testing with the `INTELLIGENCE_STORE` environment variable.

## Command line

Show statistics:

```bash
npm run intelligence:stats
```

Search:

```bash
node scripts/intelligence-cli.js search "IIS reverse proxy" --limit 5
```

Recommend from a context file:

```bash
node scripts/intelligence-cli.js recommend examples/web-intelligence/roofing-opportunity-context.json
```

Ingest an inspection:

```bash
node scripts/intelligence-cli.js ingest examples/automated-inspector/report.json --kind inspection-report
```

Ingest a repair plan:

```bash
node scripts/intelligence-cli.js ingest examples/autonomous-repair/repair-plan.json --kind repair-plan
```

Record outcome feedback:

```bash
node scripts/intelligence-cli.js feedback RECORD_ID success --score-delta 4 --project "Project name"
```

Reset the working store to the original seed:

```bash
node scripts/intelligence-cli.js reset --confirm
```

## Governance and safety

- Source provenance must remain attached.
- A one-time observation must not be labeled proven.
- Automated ingestion does not authorize source or production changes.
- Industry insights must not be treated as legal, compliance, or safety advice without responsible review.
- Sensitive project data should not be copied into summaries, tags, or feedback notes.
- Failed patterns remain visible so the system can learn what not to repeat.
- Deprecation is preferred over silent deletion when knowledge has history.
- The local write API should not be exposed publicly without authentication and authorization.

## Verification

`npm run test:intelligence` validates:

- Seed size and all eight record types
- Search relevance and textual match evidence
- Context recommendations
- Duplicate merging
- Inspection grouping and ingestion
- Repair and manifest ingestion
- Feedback metrics and confidence update
- Atomic save and reload

The full `npm test` suite also verifies the Control Center, generator, inspector, repair loop, and quality audit.