docs: consolidate and de-clutter the documentation tree (#306 )

CLAUDE.md rewritten (708 -> ~320 lines): four overlapping release
sections collapsed to one, stale v1->v35 schema history dropped (it
lives in CHANGELOG), marketplace endpoint internals and verbose
process sections moved out or tightened.

New focused docs:
- docs/RELEASING.md - release process, deploy workflows, CI quirks
  (RELEASE_TEMPLATE.md folded in as an appendix)
- docs/marketplace.md - marketplace ingestion + re-serving internals
- docs/README.md - documentation index by audience, linked from
  README.md and CLAUDE.md

Archived under docs/archive/: docs/superpowers/ (52 historical
planning artifacts), HACKATHON.md, pd-ps-comments.md,
security-audit-2026-04.md, future/NOTIFICATIONS.md.

Removed the docs/auto-install.md stub. Fixed dangling links in
connectors/jira/README.md and dev_docs/README.md, repointed
code/doc references to archived paths.

2026-05-14 18:54:22 +00:00

2.5 KiB

Raw Blame History

New: docs/PLATFORM_SETUP.md is the consolidated operator playbook. This doc covers a focused subset; check the playbook first.

Quick Start Guide

Prerequisites

Python 3.10+
Docker + Docker Compose (for production deployment)
Data source credentials (Keboola token, BigQuery project, etc.)

Local Development Setup

Clone the repository:

git clone <repo-url>
cd ai-data-analyst

Create virtual environment and install dependencies:

python3 -m venv .venv && source .venv/bin/activate
uv pip install ".[dev]"

Configure your instance:

cp config/instance.yaml.example config/instance.yaml
# Edit config/instance.yaml with your settings

Set up environment variables:

cp config/.env.template .env
# Edit .env with your data source credentials

# Via CLI
agnes admin register-table --source-type keboola --bucket "in.c-crm" --table "company" --query-mode local

# Or start the server and use the web UI at /admin/tables

Start the FastAPI server:
```
uvicorn app.main:app --reload
```

Trigger a data sync:

curl -X POST http://localhost:8000/api/sync/trigger

Docker Deployment

# Start app + scheduler
docker compose up

# Include telegram bot
docker compose --profile full up

# HTTPS mode — Caddy + corporate-CA certs
docker compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.tls.yml \
    --profile tls up -d

See DEPLOYMENT.md for full server setup instructions.

Using with Claude Code

Open the project in Claude Code. The CLAUDE.md file will guide the AI assistant through setup and analysis workflows.

Analyst Setup

Visit your instance URL (e.g., https://data.yourcompany.com)
Sign in with your company email
Access data through the API or download parquets for local analysis

Analysis Workflow

Sync latest data: curl -X POST https://data.yourcompany.com/api/sync/trigger
Open Claude Code in your project directory
Ask Claude to analyze your data using DuckDB

Hackathon

See archive/HACKATHON.md for the deploy-and-develop playbook (archived event runbook). Per-developer dev VMs are the supported pattern — point your VM at your branch image with gcloud compute ssh <vm> --command "sudo sed -i 's/^AGNES_TAG=.*/AGNES_TAG=dev-<slug>/' /opt/agnes/.env && sudo /usr/local/bin/agnes-auto-upgrade.sh".

2.5 KiB Raw Blame History