Repository Layout

This repository mixes product code, astrology research, oracle artifacts, and local experimentation. To keep the worktree usable, follow these layout rules.

Core Areas

<repo>/frontend/
- current Next.js production web application
<repo>/deploy/
- production container topology and operational source of truth; start with deploy/README.md
<repo>/mcp_server.py
- adjudicator-facing MCP entrypoint
<repo>/scripts/
- reusable project code and maintained tooling
<repo>/tests/
- maintained regression and contract tests
<repo>/references/
- durable knowledge assets, oracle cases, and frozen methodology

Research

<repo>/docs/research/
- active research and current audits
<repo>/docs/research/archive/
- historical round notes and local draft research

Historical Working Logs

<repo>/task_plan.md
<repo>/findings.md
<repo>/progress.md

These root files preserve earlier implementation history and may mention retired paths or commands. They are not runtime or deployment instructions. Use README.md for current local development and deploy/README.md for production.

Local Scratch

<repo>/scratch/local/scripts/
- one-off debugging scripts, temporary probes, ad hoc runners
<repo>/scratch/local/outputs/
- local generated JSON, text dumps, temporary reports

These paths are local-only and ignored by git.

Local Runtime Noise

The following should stay out of normal versioned work:

<repo>/.agents/
<repo>/venv_vedastro/
<repo>/scratch/local/

Practical Rule

Before adding a new file, decide which lifecycle it belongs to:

reusable project asset
active research note
archived research
local scratch script
local generated output

If it is category 4 or 5, do not leave it in the repo root.

1.8 KiB Raw Permalink Blame History