00-start-here.md

Start here

These docs exist to help ChatGPT and other LLMs produce consistent, well-engineered Vroq apps.

The goal is not to restate everything that can be learned quickly by reading the source. The goal is to encode the preferred way to work in this codebase so fresh chats can read the docs and then:

write new apps
improve existing apps
debug and fix bugs
refactor code without drifting into hacks

Primary goals

When working in Vroq apps, prioritize these outcomes:

clear intention in code
consistent naming
consistent directory structure
small files with clear responsibilities
feature grouping instead of scattered logic
reuse of existing code before creating new code
real fixes at the owning layer instead of local hacks
reducer and action design that supports debugging and LLM reasoning

How to use these docs

Read these docs as an engineering style guide and editing protocol, not just as framework reference.

Use them to answer questions like:

where should this code live?
should this be a component, section, or feature?
should this logic reuse an existing helper?
should this edit be a patch or a rewrite?
how should this app bootstrap itself?
how should store, reducers, actions, sections, and API clients be separated?

Core rules

These are the highest-priority rules across the whole doc set:

preserve and improve consistency
prefer patching existing files over rewriting them
group code by feature
keep files small and purposeful
reuse existing helpers, sections, components, and patterns before adding new ones
fix root causes, not symptoms
keep presentation-only UI separate from store-aware feature code when possible
use reducers and actions to keep state changes explicit and debuggable
keep transport and API code out of presentational UI files
follow the standard app bootstrap and directory structure

Vroq MCP editing rules

When editing app files through Vroq MCP:

prefer patching over rewriting
make focused edits instead of broad rewrites
inspect existing structure before changing architecture
preserve useful existing patterns unless there is a strong reason to improve them

If a file must be deleted, do not delete it directly. Instead replace its contents by starting the file with these two lines:

// DELETED
this line is intentionally not commented to cause an error if we still use this file

This makes accidental remaining usage fail loudly.

What these docs focus on

These docs should mainly document:

house style
naming conventions
directory structure
file roles
bootstrap patterns
components vs features vs sections
reducer and action design
API and BigTree design patterns
styling rules for consistent apps
editing and refactoring workflow for LLMs

These docs should not spend most of their space repeating source code details that are easy to learn directly from the code.

Standard for all future docs

Each doc file should be:

small
opinionated
practical
easy to retrieve in isolation
focused on one main decision or topic

The purpose of this doc set is to help fresh chats become disciplined Vroq engineers quickly.

Start here

Start here

Primary goals

How to use these docs

Core rules

Vroq MCP editing rules

What these docs focus on

Read next

Standard for all future docs