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.

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

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:

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
• Crawler integration handoff
• Example normalized batch
• Release evidence
• Factory evaluation and papercuts

Verification

Focused product verification:

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

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.