# ChangeSignal

ChangeSignal is a source-backed product-intelligence shell for tracking how
technology companies change their public documentation over time.

It is designed to answer:

- What did a company ship or change?
- Which product areas are receiving the most investment?
- How quickly is each company moving?
- Which meaningful changes never appeared in the public changelog?
- What evidence can GTM, customer-success, support, and competitive-intelligence
  teams use in messaging?

This repository does **not** contain a crawler. It provides the web product,
normalized ingestion contract, durable data boundaries, CLI, HTTP/OpenAPI, and
MCP surfaces required to integrate an existing crawler later.

## Current status

The repository is a usable, fake-safe product shell with:

- overview, change feed, evidence detail, companies, product areas,
  subscriptions, analytics, documentation sources, and messaging views;
- five synthetic companies and fifteen synthetic documentation changes;
- seventeen shared operations projected across web, HTTP, CLI, and MCP;
- a real MCP stdio transport;
- a versioned `crawler-change-batch.v1` validation boundary; and
- explicit preview or `not-configured` responses for actions that would require
  persistence, delivery, crawling, or a model provider.

Fixture data is synthetic and does not represent live crawler output.

## Run the web app

Requirements: Node.js 22 and pnpm 10.12.1.

```bash
pnpm install --frozen-lockfile
pnpm --dir apps/web dev --port 8421 --strictPort
```

Open `http://127.0.0.1:8421`.

Primary routes include:

- `/` — product-intelligence overview
- `/changes` — searchable change feed
- `/companies` — monitored-company catalog
- `/subscriptions` — watchlists and digest preferences
- `/analytics` — velocity, investment areas, and changelog gaps
- `/sources` — documentation-source readiness
- `/agents` — evidence-grounded messaging analyst
- `/api` — API, CLI, and MCP catalog

## CLI

```bash
pnpm changesignal overview
pnpm changesignal companies list
pnpm changesignal changes list --company relaydesk
pnpm changesignal changes get relaydesk-routing-controls
pnpm changesignal sources list --company relaydesk
pnpm changesignal messaging brief relaydesk-routing-controls
pnpm changesignal ingestion validate \
  --file docs/examples/change-signal/crawler-change-batch.v1.json
pnpm changesignal mcp tools
```

Add `--json` to supported commands for the shared machine-readable operation
envelope.

## MCP

Launch the stdio server with:

```bash
pnpm changesignal mcp serve
```

The server supports MCP initialization, tool discovery, reviewed read tools,
source-mapping previews, messaging briefs, and bounded crawler-batch validation.
Persistence mutations remain disabled until authentication, audit, idempotency,
and storage are connected.

## Integrating crawler output

The crawler owner supplies one redacted representative payload plus transport,
authentication, stable-ID, retry, replay, and snapshot-reference details. A
provider adapter then maps the native payload into `crawler-change-batch.v1`;
crawler-specific logic stays outside the web, CLI, MCP, capability, and workflow
layers.

See:

- [Product plan](docs/change-signal-product-plan.md)
- [Crawler integration handoff](docs/change-signal-crawler-handoff.md)
- [Example normalized batch](docs/examples/change-signal/crawler-change-batch.v1.json)
- [Release evidence](docs/change-signal-release-evidence.json)
- [Factory evaluation and papercuts](docs/factory-evaluation.md)

## Verification

Focused product verification:

```bash
pnpm --dir packages/change-signal test
pnpm --dir packages/change-signal typecheck
pnpm --dir apps/cli test
pnpm --dir apps/cli typecheck
pnpm --dir apps/web test
pnpm --dir apps/web typecheck
pnpm --dir apps/web build
```

The generated foundation retains several upstream factory verification defects.
They are documented without weakening the affected tests in
`docs/factory-evaluation.md`.

## Architecture

```text
web routes -> screens -> features -> blocks -> Saas UI/shared primitives
API/CLI/MCP -> shared operation registry -> capabilities/workflows
crawler provider adapter -> normalized batch -> validation -> durable owners
storage/notifications/observability -> provider adapters
```

The application was generated from the Maestro SaaS UI factory and then built as
a product-specific shell. The factory evaluation is retained because this
repository also serves as a real-world test of that application factory.