VC Dashboard

VC Dashboard is a local-first project dashboard for Vibe-Coding projects. It reads structured metadata from each project's plan.md, validates the YAML contract, scans local project files, and shows project status, phases, progress, risks, notes, GitHub metadata, and code-size metrics in one local dashboard.

It is built for people who work with AI-assisted coding workflows and want a compact control center without a database, login, cloud service, or GitHub write access.

What It Does

• Tracks multiple local projects from one dashboard.
• Reads dashboard metadata from each project's plan.md.
• Validates the dashboard: YAML frontmatter with Zod.
• Shows project status, current phase, progress, risks, notes, and last refresh.
• Lets you edit the compact project note directly in the dashboard.
• Counts code lines as the primary community-friendly size metric.
• Keeps code characters as a precise secondary metric.
• Writes calculated refresh data to local JSON snapshots.
• Lets you register projects from the dashboard after plan.md validation.

What Stays Local

These files are intentionally ignored by Git:

• config/projects.yaml
• data/snapshots/**
• reports/generated/**
• state/*.local.json
• docs/archive/*.md
• context/*.md

Use them freely for your own projects. They should not be published with the app.

Quick Start

Install dependencies:

npm install

Create your private project registry:

npm run init:config

This creates config/projects.yaml for the included demo project. If the file already exists, it is left unchanged.

Start the dashboard:

npm run dev

Open:

http://localhost:3000

localhost always means the user's own computer. No shared server or maintainer machine has to stay online.

You can also skip the copy step and add the first project directly in the dashboard. The app creates config/projects.yaml after the submitted plan.md validates.

Creating A plan.md

Start here:

1. Read docs/workflow-plan.md to turn an idea into a dashboard-ready plan.
2. Copy the YAML template from docs/plan-md-template.md.
3. Keep schema values in English, for example active, pending, completed, high.
4. Register the project in the dashboard with the local path and plan.md. The project title and id are derived from the folder name and must match dashboard.project.id.

GodMode is optional. If you use it, let it help create and validate the plan.md; the dashboard itself only requires valid YAML metadata.

Demo Project

The repository includes a minimal valid plan:

examples/demo-project/plan.md

After running npm run init:config, validate and collect the demo snapshot:

npm run validate:projects
npm run collect:projects

You can still create config/projects.yaml manually by copying config/projects.example.yaml, but npm run init:config avoids placeholder path editing for the demo.

Documentation Map

• docs/workflow-plan.md: idea-to-plan workflow, with and without GodMode.
• docs/plan-md-template.md: copy/paste plan.md template and schema rules.
• docs/update-workflow.md: versioning and update workflow.
• docs/community-release.md: checklist before sharing the repository publicly.
• docs/design.md: compact, work-focused UI baseline.
• config/projects.example.yaml: public example registry.
• examples/demo-project/plan.md: minimal dashboard-ready project plan.

Plan YAML Requirements

Every registered project needs YAML frontmatter with a top-level dashboard: block. Optional dashboard.notes appears as the longer note line in the dashboard. Optional dashboard.short_note appears as a compact table note and is limited to 12 characters. Quote YAML values when the text contains a colon.

Rules enforced by the dashboard:

• dashboard.schema_version must be 1.
• dashboard.short_note may be empty, but when set it must be 12 characters or shorter.
• dashboard.project.id must match the id in config/projects.yaml.
• dashboard.project.status must be one of active, paused, completed, or archived.
• dashboard.lifecycle.version should use semantic version format, for example 1.0.0.
• dashboard.lifecycle.baseline.code_chars must be a non-negative integer.
• dashboard.lifecycle.baseline.code_lines is optional and should be a non-negative integer when used.
• dashboard.github.enabled must be a boolean. Other GitHub fields may be text or empty.
• dashboard.code.include_extensions must contain lowercase extensions starting with ., for example .ts or .blade.php.
• dashboard.code.exclude_paths must be relative path prefixes with /, no absolute paths, no .., no URL scheme.
• dashboard.code.exclude_files must be basenames only, no folders, no .., no URL scheme.
• dashboard.progress.done and dashboard.progress.total must be non-negative integers.
• dashboard.progress.percent must equal round(done / total * 100) when total > 0.
• dashboard.progress.code_chars_at_100_percent stays empty until the project reaches 100%. When percent is 100, it must be filled with the current code_chars_current value from the snapshot at that moment.
• dashboard.progress.code_lines_at_100_percent follows the same rule for code lines.
• dashboard.current_phase.id must reference a phase in dashboard.phases.
• dashboard.current_phase.title and dashboard.current_phase.status must match the referenced phase.
• Phase ids must be unique. Phase status must be pending, active, completed, or deferred.
• Risk probability and impact must be low, medium, high, or critical.
• Risk status must be open, active, mitigated, accepted, resolved, closed, or deferred.
• Next-step priority must be low, medium, or high.
• Next-step status must be open, done, blocked, skipped, or deferred.
• Empty values are allowed only where the schema expects nullable text, for example completed_at:.

Metrics

VC Dashboard tracks code lines and code characters. Code lines are the primary friendly metric because they are familiar in community discussions. Code characters remain useful as a precise secondary size metric that does not change because of line wrapping style.

Neither code lines nor code characters measure quality, complexity, or usefulness. They only describe project size.

Validation

Use the focused validation scripts:

npm run typecheck
npm run validate:projects
npm run collect:projects
npm test
npm run build
npm audit --omit=dev

Local Safety

• The dev server binds to 127.0.0.1, which is the local machine behind localhost.
• Only projects listed in config/projects.yaml are scanned.
• Browser requests cannot submit arbitrary filesystem paths for refresh.
• The Windows folder picker opens only after a local button click and returns one selected folder path.
• Write endpoints use local-origin and CSRF checks.
• GitHub integration is metadata/link-only in this version.