OverviewREADME & Quick Start
Repository quick start, CLI commands summary, and local analysis architecture.
README.mdDocumentation
The source documents are the current documentation.
TRACE is actively being developed. These documents point directly to in-tree architecture, specification records, CLI manuals, and GitHub App integrations rather than a fabricated marketing guide.
In-Tree Records
Authoritative repository documents.
Durable Markdown and design records versioned alongside TRACE engine code.
DocumentPurpose & ScopeRepository PathLink
WorkflowLocal-to-Dashboard Workflow
First connection walkthrough, signed artifact staging, review boundaries, and sync transport.
DOC/local-dashboard-workflow.mdArchitectureTechnical Overview & .trace RFC
AST boundary rules, .trace schema v0.1 specification, and source-exclusion guarantees.
DOC/technical-overview.mdOverviewProject Overview & Principles
Product thesis, developer coordination model, and noise-elimination principles.
DOC/project-overview.mdIntegrationGitHub App & Webhooks
Signed webhook pipelines, event deduplication, idempotency tokens, and OAuth scopes.
DOC/github-app-setup.mdDesignDesign Specification
Authoritative UI/UX rules, typography scales, dark-first color universe, and component design.
Design-system/TRACE-DESIGN-SPEC.mdInternal / ContributorImplementation Roadmap
Internal contributor phase execution breakdown, non-negotiable invariants, and test coverage standards.
Implementation-Prompts/README.mdExecution Pipeline
Local to dashboard workflow.
Deterministic AST analysis occurs entirely on your machine. Dashboard synchronization is an optional, source-free projection.
01
trace analyzeLocal AST Extraction
CLI parses repository symbols, commits, and diffs on your local machine.
Raw source stays on local disk02
trace report dailyVersioned Markdown Record
Human-readable artifacts with structured frontmatter are written directly to .trace/.
Committed to repository Git tree03
trace sync --dry-runDry-Run Verification
Inspect the cryptographic manifest to verify no private code or secrets are synchronized.
sourceCodeIncluded: false check04
trace syncProjection Sync
Approved metadata snapshot is transmitted over HTTPS to project on the web UI.
Ephemeral dashboard presentationLocal CLI Manual
Build the project record without uploading source.
Run the CLI locally from your repository root to extract change evidence, verify rules, and generate Markdown reports.
trace initScaffold the root `.trace/` directory structure, local configuration, and schema definitions.
trace analyze changesDeterministic AST analysis of staged diffs, branch divergence, and symbol-level impacts.
trace report daily --write --yesSynthesize verified repository changes, merged pull requests, and architectural drift into a daily report.
trace validateVerify that all `.trace/` Markdown files, ADRs, and indexes strictly comply with schema v0.1.
Core Guarantee: Generated files in .trace/ remain durable repository records versioned with Git. Local analysis never contacts an external network.
Sync & Verification
Analyze locally. Sync only the record you approve.
Connect the CLI to your GitHub workspace, inspect the dry-run artifact manifest, and publish a source-free snapshot.
trace loginAcquire an isolated, revocable CLI authentication credential via browser handshake.
trace connectBind the local Git repository remote to its registered TRACE cloud workspace.
trace analyzeExecute full repository AST indexing and write structured understanding to `.trace/`.
trace sync --dry-runInspect the exact manifest of metadata to be synchronized without transmitting any payload.
trace syncPublish the approved, source-free metadata snapshot to the cloud projection layer.
Boundary Rule: Source files, raw code snippets, API secrets, confidential comments, and browser credentials are automatically excluded by transport schema validators.