<!--
Copyright (c) 2026 qbitOS / ugrad.ai. All rights reserved.
SPDX-License-Identifier: Apache-2.0
Source: https://github.com/qbitOS/qbitos-freya
Provenance: freya-repo-readme
-->

# qbitos{freya} — FreyaUnits

Canonical FreyaUnits deployment surface for:

- `freya.ugrad.ai`
- `freya.qbitos.ai`

## Runtime Stack

- `quantum-prefixes.js`
- `qbit-dac.js`
- `qbit-steno.js`
- `qbit-preflight.js`
- `history-search-engine.js`
- `sw.js`

## Surfaces in this repo

- `index.html` — start route that opens the landing surface
- `freya-landing.html` — launch/showcase page for fast entry
- `freya-units.html` — full FreyaUnits web app (uvspeed parity)
- `freya-terminal.html` — terminal lane for `econ` and `expr` commands
- `freya` — unified CLI (`math`, `chat`, `models`, `market`, `code`) with multi-backend routing
- `codex_api.py` — pullable Freya Codex API service (deploy target: `erika.qbitos.ai`)
- `tools/freya-math-engine.js` — reusable browser/Node math engine extension
- `tools/freya-math-cli.py` — terminal CLI for quick data-econ + expression math
- `tools/freya-hexcast-cli.py` — 8-bit dither CLI for terminal art + character packs

## Control Envelope

`DAC/Prefix/Steno/Iron-Line/Preflight/search-history controls`

## Terminal usage

```bash
uv run python tools/freya-math-cli.py econ --tb 474000000 --cost 400 --pct-a 20 --pct-b 2
uv run python tools/freya-math-cli.py expr "sin(pi/4)^2 + cos(pi/4)^2"
uv run python tools/freya-hexcast-cli.py render path/to/ErikaFreya.png --width 90
uv run python tools/freya-hexcast-cli.py pack ErikaFreya path/to/ErikaFreya.png
uv run python tools/freya-hexcast-cli.py batch
./freya telemetry --dry-mass-kg 120000 --fuel-mass-kg 300000 --thrust-n 7600000 --isp-s 300 --duration-sec 20 --step-sec 1 --jsonl
./freya telemetry --input bench/telemetry-sample.jsonl --input-format jsonl --phase-meco-sec 160 --phase-seco-sec 510 --jsonl
./freya telemetry-validate --input bench/telemetry-sample.jsonl --input-format jsonl --max-q-kpa 45 --max-accel-g 6 --min-twr-powered 1.1
./freya telemetry-compare --actual bench/telemetry-run-a.jsonl --target bench/telemetry-run-b.jsonl --format jsonl
./freya market convert --amount 100 --from USD --to EUR
./freya market convert --amount 0.25 --from BTC --to USD
./freya market quote --symbol AAPL --market stock
./freya market quote --symbol ETH --market crypto
./freya chemistry periodic --query Si
./freya chemistry bond --a Na --b Cl
./freya geometry plot --expr "sin(x)" --x-min -6.28 --x-max 6.28 --steps 360
./freya geometry shape --type sphere --a 5
./freya code qr --text "https://freya.qbitos.ai/menu" --size 320 --out bench/freya-hexcast-qr.png
./freya code lookup --code 9780140328721
./freya code codec --from ascii --to hex --text "freya"
./freya code codec --from hex --to binary --text "6672657961"
./freya code codec --from binary --to ascii --text "0110011001110010011001010111100101100001"
./freya code quicklist --codes "9780140328721,737628064502,012345678905"
./freya code dam-tree --root "kbatch/ingredients" --input-json bench/ingredients.json
./freya time convert --smpte 00:01:12:15 --fps 30
./freya time synclock --reference-unix 1710000000.120 --device-unix 1710000000.184 --reference-end-unix 1710000060.120 --device-end-unix 1710000060.186
./freya time calibrate --distance-m 402.336 --duration-sec 11.8 --mass-kg 1450 --power-w 420000 --clock-offset-ms 2.8 --clock-drift-ppm 18
./freya time jawbreaker-race --distance-m 402.336 --laps 3 --splits "11.8,11.6,11.4" --fps 30 --reference-unix 1710000000.12 --device-unix 1710000000.14
./freya music transpose --notes "C4,E4,G4,B4" --semitones 2 --key D
./freya music daw-sync --bpm 128 --sample-rate 48000 --buffer-size 256 --ppq 960 --bars 8 --fps 30
./freya music binaural --base-hz 220 --beat-hz 8 --duration-sec 120
./freya quantum run --qubits 2 --program "h 0; cx 0 1; measure" --shots 2048
./freya chunk list
./freya chunk run --id models.doctor
./freya chunk run --id telemetry.alert --input bench/telemetry-run-a.jsonl --input-format jsonl
./freya chunk run --id telemetry.stream --input bench/telemetry-run-a.jsonl --input-format jsonl --live --replay-speed 2.0
./freya chunk run --id telemetry.plot --input bench/telemetry-run-a.jsonl --input-format jsonl --output bench/telemetry-plot.html
./freya chunk run --id quantum.preset --preset ghz --qubits 3 --shots 1024
./freya chunk run --id quantum.algorithm --name shor --number 15
./freya chunk run --id gis.convert --from-crs WGS84 --to-crs UTM --lat 37.7749 --lon -122.4194
./freya chunk run --id math.stats --data-file bench/stats.csv --method regression --x-col x --y-col y
./freya chunk run --id math.diaspora --diaspora-method abacus --operation mul --a-value 147 --b-value 26
./freya chunk run --id math.diaspora --diaspora-method lattice --operation mul --a-value 123 --b-value 45
./freya chunk run --id history.livecalc --diaspora-method egyptian --operation mul --a-value 27 --b-value 34 --history-label "Nile trade ledger"
./freya chunk run --id econ.finance --cashflows "-1000,200,300,400,500" --rate 0.1 --include-irr
./freya chunk run --id cloud.upload --provider aws --bucket my-bucket --file-path bench/results.jsonl
./freya chunk run --id agents.create --agent-name mission-ops --agent-script mission_ops.py
./freya chunk run --id plugins.install --plugin-name telemetry-pack
./freya chunk run --id bench.run --bench-command "./freya math expr 1+1" --iterations 20
./freya chunk run --id time.synclock --reference-unix 1710000000.120 --device-unix 1710000000.184 --reference-end-unix 1710000060.120 --device-end-unix 1710000060.186
./freya chunk run --id time.calibration --distance-m 402.336 --duration-sec 11.8 --mass-kg 1450 --power-w 420000 --clock-offset-ms 2.8 --clock-drift-ppm 18
./freya chunk run --id jawbreaker.race --distance-m 402.336 --laps 3 --splits "11.8,11.6,11.4" --fps 30 --reference-unix 1710000000.12 --device-unix 1710000000.14
./freya chunk run --id music.transpose --notes "C4,E4,G4,B4" --semitones 2 --key D
./freya chunk run --id music.dawsync --bpm 128 --sample-rate 48000 --buffer-size 256 --ppq 960 --bars 8 --fps 30
./freya chunk run --id music.binaural --base-hz 220 --beat-hz 8 --duration-sec 120
nu scripts/pre.nu
./freya chunk scaffold --id custom.my-new-component --title "My New Component"
./freya rules validate --file rulesets/default.ruleset.json
./freya rules activate --file rulesets/default.ruleset.json
./freya artifact add --kind report --name readiness --path reports/readiness.json --meta-json '{"scope":"prod"}'
./freya artifact list --kind report
./freya artifact set-lifecycle --id <artifact-id> --lifecycle archived
./freya rag index --source . --glob "*.md"
./freya rag query --query "erika api bridge" --top-k 5
./freya chat --session demo --use-rag "summarize readiness"
./freya models --route-task code --family codellama
./freya agent memory-write --agent planner --key objective --value "ship readiness"
./freya agent memory-read --agent planner
./freya enterprise mistral-route --task code
./freya enterprise compliance-check --role admin --action enterprise.ops-report
./freya enterprise audit-log --actor ci --role operator --action deploy --resource erika --status PASS --meta-json '{"release":"v1"}'
./freya enterprise eval --prompt "Summarize release risk in 3 bullets" --backends "mistral,ugrad,lmstudio,ollama,huggingface"
./freya enterprise eval-suite --suite-file enterprise/eval-suite.json
./freya enterprise ops-report --window-hours 24
```

## Freya Codex Pull API (erika.qbitos.ai)

Canonical production base:

- `https://erika.qbitos.ai/api/v1/codex/context`
- `https://erika.qbitos.ai/api/v1/codex/chart-data`
- `https://erika.qbitos.ai/api/v1/codex/split-chart`
- `https://erika.qbitos.ai/api/v1/codex/live-astrology`
- `https://erika.qbitos.ai/api/v1/pay/plans`
- `https://erika.qbitos.ai/api/v1/pay/checkout-link`
- `https://erika.qbitos.ai/api/v1/system/integration`
- `https://erika.qbitos.ai/api/v1/freya/tools`
- `https://erika.qbitos.ai/api/v1/freya/run`

Local run:

```bash
uv run python codex_api.py --host 0.0.0.0 --port 8787
```

Example request:

```bash
curl -X POST "https://erika.qbitos.ai/api/v1/codex/context" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "subject": {
      "name": "Freya",
      "year": 1990,
      "month": 5,
      "day": 1,
      "hour": 10,
      "minute": 0,
      "longitude": 12.4964,
      "latitude": 41.9028,
      "timezone": "Europe/Rome",
      "zodiac_type": "Tropical",
      "houses_system_identifier": "P"
    },
    "theme": "dark",
    "language": "EN",
    "custom_title": "Freya Codex"
  }'
```

Production go-live pack (included in repo):

- `deploy/env/codex_api.env.example` (copy to `/etc/qbitos/freya-codex.env`)
- `deploy/systemd/freya-codex-api.service`
- `deploy/nginx/erika.qbitos.ai.conf` (Nginx reverse proxy + TLS)
- `deploy/caddy/Caddyfile.erika.qbitos.ai` (Caddy alternative)
- `scripts/deploy-codex.sh` (one-command rsync + systemd restart + health probe)

Go-live quickstart:

```bash
chmod +x scripts/deploy-codex.sh
./scripts/deploy-codex.sh
curl -fsS https://erika.qbitos.ai/health
```

Production readiness gate:

```bash
# Safe local dry-run (default):
nu scripts/prod-ready.nu

# Full live verification (DNS/TLS/API/auth):
PROD_DRY_RUN=0 FREYA_ERIKA_API_KEY="YOUR_KEY" nu scripts/prod-ready.nu

# Full live verification with strict IPv6 AAAA requirement (default):
PROD_DRY_RUN=0 PROD_REQUIRE_AAAA=1 FREYA_ERIKA_API_KEY="YOUR_KEY" nu scripts/prod-ready.nu

# If testing local-only or IPv4-only staging:
PROD_DRY_RUN=0 PROD_REQUIRE_AAAA=0 FREYA_ERIKA_API_KEY="YOUR_KEY" nu scripts/prod-ready.nu
```

Notes:

- The API is live only after DNS + reverse proxy + systemd service are deployed on your host.
- Set a real `CODEX_API_KEYS` value in `/etc/qbitos/freya-codex.env` before exposing `/api/v1/*`.
- If you use Nginx, symlink `deploy/nginx/erika.qbitos.ai.conf` into `sites-enabled` and reload Nginx.
- `GET /api/v1/system/integration` reports DAC/Iron Line/Quantum Gutter Prefix/Steno/Preflight flags.
- `POST /api/v1/freya/run` is whitelist-only and API-key protected (no arbitrary shell execution).
- `scripts/prod-ready.nu` checks AAAA (IPv6) by default in live mode.

IPv6 AAAA go-live checklist:

- Add DNS `AAAA` for `erika.qbitos.ai` to your server IPv6 address.
- Keep IPv4 `A` record too for dual-stack reachability.
- Nginx config already includes IPv6 listeners (`listen [::]:80`, `listen [::]:443`).
- Open firewall for TCP `80/443` on IPv6.
- Re-run: `PROD_DRY_RUN=0 PROD_REQUIRE_AAAA=1 FREYA_ERIKA_API_KEY="YOUR_KEY" nu scripts/prod-ready.nu`

## Cost model (once live)

- API plans are built in: Starter `$29/mo`, Pro `$99/mo`, Enterprise `$499/mo` (`/api/v1/pay/plans`).
- Hosting estimate: small VPS + TLS proxy is typically `$10-$40/mo`; managed platform can be higher.
- Domain/DNS estimate: usually `$1-$5/mo` equivalent (depending on registrar/TLD).
- Total practical floor: about `$40-$70/mo` for a small production footprint (Starter + VPS + domain).

## API bridge from CLI

`freya` can call `erika.qbitos.ai` directly:

```bash
./freya erika health
./freya erika integration
./freya erika plans
./freya erika tools
./freya erika run --tool math.expr --args-json '{"expression":"(2+2)*4"}'
./freya erika context --subject-json '{"name":"Freya","year":1990,"month":5,"day":1}' --theme dark --language EN
```

## Governance + RAG + Memory

- Rulesets: `rulesets/schema.json`, `rulesets/default.ruleset.json`
- Active ruleset state: `.freya/active-ruleset.json`
- Artifact lifecycle index: `.freya/artifacts/index.json`
- Session memory: `.freya/sessions/*.json`
- Agent collaboration memory: `.freya/agent-memory.json`
- Local RAG index: `.freya/rag-index.json`

## Enterprise Pack

- Mistral route policy: `enterprise/mistral-enterprise-pack.json`
- RBAC policy: `enterprise/rbac-policy.json`
- Eval prompt suite: `enterprise/eval-suite.json`
- Readiness dossier: `MISTRAL_ENTERPRISE_READINESS.md`
- Kubernetes ops pack: `deploy/k8s/`

## Phase A-C Initial Chunk Coverage (1-5)

- 1) Multi-backend model support: `models.doctor`, `models.switch`
- 2) Enhanced telemetry (stream/validate/plot/compare): `telemetry.stream`, `telemetry.alert`, `telemetry.plot`
- 3) Quantum extensions (presets + algorithms): `quantum.preset`, `quantum.algorithm`
- 4) GIS integration: `gis.convert`, `gis.map`
- 5) Advanced math/economics + diaspora/live-history: `math.stats`, `math.diaspora`, `econ.finance`, `history.livecalc`

## Mistral Vibe agent discovery

- `AGENTS.md` at repo root for agent context/autodiscovery
- `.vibe/skills/freyaunits/SKILL.md` for local skill registration in Vibe-style runtimes
- `AI_INDEX.md` for machine-first entry and routing
- `IMPLEMENTATION_ORDER.md` for deterministic implementation flow
- `BACKEND_MATRIX.json` for backend/env/model alias mapping

Reference: [Mistral Agents & Skills](https://docs.mistral.ai/mistral-vibe/agents-skills)

## Search/assistant indexing

- `robots.txt` for crawler allow + sitemap location
- `sitemap.xml` with primary Freya URLs
- Open Graph, Twitter, canonical, robots, and JSON-LD metadata in top pages
- `llms.txt` for AI crawler/service discovery hints

## Benchmark evidence pack

- `BENCHMARK.md` — verdict policy and pass criteria
- `bench/stock-prompt.txt` — fixed benchmark prompt
- `bench/result-schema.json` — machine-checkable run schema
- `bench/results.jsonl` — append-only run log
- `bench/RUNBOOK.md` — execution and publication checklist

## Source

Primary source app evolves in `qbitOS/uvspeed`; deploy packaging is published via
`qbitOS/uvmis-evolution-agent` with runtime parity (no requirement to mirror every folder structure).