How Zeno Works

Core workflow

1. Scan the local project — Zeno inspects repository structure, source patterns, routes, dependencies, scripts, tests, metadata, and environment usage.
2. Detect the project type — Zeno classifies the repository as a landing page, SaaS app, dashboard, developer tool or CLI, backend API, documentation site, or ecommerce project. Ambiguous results require confirmation.
3. Trace the critical path — Zeno identifies the primary action users must complete and checks whether the repository appears to connect that action to a real handler, route, integration, database, or filesystem outcome.
4. Run deterministic checks — Local static analysis creates evidence-backed findings before AI synthesis is used.
5. Classify the risk — Findings are separated into hard blockers, soft blockers, and code ownership risks. Each receives a severity and certainty level.
6. Evaluate the launch context — Private preview, public launch, and paid traffic readiness are judged separately.
7. Produce a bounded report — Structured-output limits, repair retries, and deterministic fallback prevent malformed model output from being printed to the terminal.
8. Let the human decide — Zeno recommends the safest next step and identifies what still needs runtime verification.

Scope and limits

Zeno uses static repository evidence. It can detect that a form has no visible submit integration, that a protected route lacks an apparent guard, or that a CLI command is not connected to an entrypoint. It cannot prove that a deployed service works, that third-party credentials are valid, or that every runtime branch succeeds.

$ npx zenoai

Project type: Landing page (94% confidence)
Critical path: Visitor -> submit email -> captured lead

HARD BLOCKER / CONFIRMED
The form submit handler only updates local state.
No route, server action, persistence, or capture provider was found.

NEEDS RUNTIME VERIFICATION
Verify success and failure states after the capture endpoint is connected.

Severity and certainty

Severity describes the consequence of a problem. Certainty describes how strongly the repository supports the finding. These are separate dimensions.

• Confirmed — directly supported by repository evidence
• Likely — strong evidence exists, but relevant behavior may live outside the scanned path
• Needs verification — static analysis cannot resolve the runtime behavior
• Inferred — a plausible risk based on incomplete or indirect evidence

Operating principles

Critical paths first. A broken signup, checkout, capture form, authentication flow, CLI entrypoint, or data write outranks metadata, analytics, tests, and refactoring.

Do not confuse static evidence with runtime proof. Zeno reports what the repository supports and explicitly calls out what needs execution or manual verification.

Read before touching. Ship-readiness and security actions are read-only. Cleanup and splitting apply conservative safety gates.

Prefer small safe improvements. Cleanup favors contained changes. Large-file splitting only extracts clearly separable static content.

Keep full evidence locally. Reports are saved as JSON, HTML, and CSV. The HTML report can be printed or saved as PDF through the browser.

Skip files when the safest change is no change. Some files are messy but cohesive. Recommending a skip is a valid outcome.