# URTH · HANDOFF — portable state of the app

**Human-readable twin:** https://apps.urthlandscaping.com/handoff.html
**Last updated:** 2026-08-15

> **If you are an AI reading this:** you are picking up ongoing work, not starting fresh.
> Read this whole file before acting, and follow the working rules in section 6.
> Do not re-litigate settled decisions. Do not "fix" things listed here as deliberate.

---

## 1. What URTH is

URTH Landscaping is a landscape design and build company in Miami.

The app turns a property measurement into a full design analysis, in this order:

    measure → site read (sun, canopy, drainage, terrain) → planting plan → priced proposal

Every downstream step is fed by the measurement, so nothing later in the chain is guessed.

Live at **https://apps.urthlandscaping.com**. It is an internal working tool with two
client-facing faces: the property report (`urth-report.html?view=client`) and the client
designer mood board.

---

## 2. The map — the tools and what each does

| Tool | File | What it does |
|---|---|---|
| Home | `home.html` | The front door. Every tool grouped by what you are trying to do. |
| Property Brain | `brain.html` | The measure engine. The core — turns a measured property into the numbers everything else spends. |
| Properties | `properties.html` | Every property as searchable rows. |
| Registry | `brain.html?tab=reg` | Add a property, open any report. |
| Site Marks | `site-marks.html` | The field walk. Walk the property with a phone, tag plants and conditions. |
| Property report | `urth-report.html` | The full read of one property. `?view=client` = the clean client-facing face. |
| Planting plan | `plan.html` | The live plant schedule and plan drawing for a property. |
| Client Designer | `designer.html` | Mood-board plant picker, filtered by the real site conditions. |
| Plant Library | `library.html` | 393 South Florida species — sun, water, salt, scorch. |
| Sun Sweep | `sun-sweep.html` | Light on the ground, hour by hour, all year. |
| Sun 3D | `sun3d.html` | The shape of the light over the whole lot. Also the aesthetic bar for the suite. |
| 3D massing | `massing.html` | Ground-aware 3D — measured canopy, house, beds. |
| Procurement | `procurement.html` | Suppliers + equipment rentals + supplier map. One hub, three tabs. |
| Estimate | `estimate.html` | Scaffold. Honest empty state — no invented prices. |
| Jobs | `jobs.html` | Scaffold. Honest empty state — no fake job feed. |
| Today | `today.html` | Landing page: lead inbox, pipeline, recent properties, build checklist. |
| System map | `status.html?view=map` | The generated picture of how every page connects. |

---

## 3. The stack

- **Repo:** `aharveyrianhard-stack/urth-property-brain`, branch `main`.
- **Deploy:** Vercel, automatic on push to `main`, live in ~60s. No build step, no manual deploy.
- **Database:** Supabase project `wadinxqplrggagkvrdag`.
  **Shared with a separate trading project ("scintilla").** URTH is being separated onto its
  own Fly.io home under the personal Google account (aharveyrianhard@gmail.com).
- **Domains:** 8 in play. The app is `apps.urthlandscaping.com`.
- **DB address:** lives in one file, `urth-config.js` (`window.URTH_DB`). No page hardcodes it
  any more. The keys there are public browser keys, public by design. A service key must never
  go in that file; server routes read env vars instead.
- **Cache proxy:** `api/c.js`. Heavy pages ask it for a pre-made answer.
- **Cache table:** `urth_cache` stores precomputed heavy renders.

---

## 4. Where things stand — recently completed

All done, pushed, and verified live:

- The **10-step front reorganization** (one shell, one navigation vocabulary; reorganization, not redesign).
- **Precompute + gzip cache** working.
- **The field walk is wired** — `site_marks` now feeds the report and the planting plan. It
  previously had *zero* consumers; this was the biggest dead end in the system.
- **Page-spec footers on every page**, fed by `page-specs.js`.
- **The generated system map** (`status.html?view=map`), built from the specs so it cannot drift.
- **Supplier-map source recovered** into the repo (it was living outside version control).
- **Supabase address pulled out of all pages** into `urth-config.js`.
- **Plant-library safety now FAILS CLOSED.** It used to fail open: if the invasive /
  do-not-use exclusion list failed to load, the error was swallowed and every plant came back
  looking vetted — a banned species was indistinguishable from an approved one.

### The performance win (measured, before → after)

| Surface | Before | After |
|---|---|---|
| Sun 3D | 43.7 MB | 1.5 MB |
| Designer | 43.7 MB | 2.3 MB |
| Report field walk | 4.9 MB | 23 KB |

---

## 5. The decision → reason map — the context-handover mechanism

`page-specs.js` holds a spec per page (`purpose`, `reads`, `writes`, `inputs`, `outputs`,
`dependencies`, `notes`) plus a `why` array of `{ decision, reason }` objects.

**Current count: 106 decision → reason pairs across 27 pages.**

It renders in two places, automatically:

1. A collapsible **"Page spec"** footer at the bottom of every page (`page-spec.js` injects it;
   hidden when `?view=client` or `?internal=0`).
2. Inside each node on the generated system map, as "Decision → reason (N)".

**The rule: whenever anything changes, the decision AND its reason get recorded there.**
That is what stops a future session from undoing a deliberate choice because it looked like a
bug, and it is why "why is it like this?" has an answer that outlives the chat it was decided in.

See it: https://apps.urthlandscaping.com/status.html?view=map

---

## 6. How Alan works — standing rules for any session

1. **Execute, do not ask** — for anything reversible. Do it, then report what you did.
2. **Never claim done without live verification.** Done = commit → push → live → measured, with
   before/after evidence in the same message. Working locally is not done.
3. **No localhost, no local-file deliverables.** Always a public URL he can open on any device.
4. **Nothing is deleted without his explicit OK.**
5. **Harvest before retire.** Take the good parts out of a page before it goes.
6. **Explain in plain words.** He is non-technical and dictates by voice. What it is, what it
   does, why it matters. A bare technical name is not communication.
7. **Keep page specs current — including the WHY.** Any change updates `page-specs.js`.
8. **No Supabase edge functions — write real code.** Settled; do not re-propose.
9. **Build mode now, security at the end.** Row-level security is deliberately OFF. This is
   intentional for the build phase — do not "fix" it and do not raise it as a finding.
10. **One canonical file per job, no sprawl.** Edit in place. No dated copies, no `_v2_final`.
    Git is the version history.

---

## 7. What's next — the live queue

### a. Reskin the CAD + planting-plan outputs (front of the queue)
The visual language work. Mood board: `proto-moodboard.html` — the same sample property drawn
three ways:
- **Architect** — a real stamped drawing set: cream paper, hairline ink, hatching instead of
  colour, dimensions, keynotes, north arrow, title block.
- **Nocturne** — the Sun 3D language brought down to a plan: dark atmospheric ground, glowing
  linework, gold used only as light.
- **Field** — not a drawing but a product: light ground, one bold flat colour per material,
  legend chips, readable on a phone in glare.

**Agreed direction: Architect's shapes + Field's colour, Nocturne for on-screen.**
Report re-skin prototype: `proto-report-v6.html`.

### b. Rebuild Sun Sweep in full 3D
Bring it up to the Sun 3D bar.

### c. Migrate to Fly.io
Off the shared Supabase project onto URTH's own home.
**Needs Alan's hands once:** sign into Fly with Google.

### d. Clean subdomain URLs
`maps.urthlandscaping.com/suppliers` needs a DNS CNAME record.

### e. Small crumbs
- `index.html` (classic launcher) has 2 stale tiles — Estimate and Jobs still point at
  `brain.html?tab=est` / `brain.html?tab=job`, but those are their own pages now
  (`estimate.html`, `jobs.html`).
- Procurement borrows the Jobs icon — it needs its own.
- `designer.html` has 8 Supabase-storage image URLs to repoint at migration.

---

## 8. Key links

| What | URL |
|---|---|
| Live app | https://apps.urthlandscaping.com/ |
| Home (front door) | https://apps.urthlandscaping.com/home.html |
| Generated system map | https://apps.urthlandscaping.com/status.html?view=map |
| Status board | https://apps.urthlandscaping.com/status.html?view=board |
| Improvement blueprint | https://apps.urthlandscaping.com/blueprint.html |
| Drawing mood board (3 treatments) | https://apps.urthlandscaping.com/proto-moodboard.html |
| Report re-skin prototype | https://apps.urthlandscaping.com/proto-report-v6.html |
| Repo | https://github.com/aharveyrianhard-stack/urth-property-brain |
| This file | https://apps.urthlandscaping.com/HANDOFF.md |
| Human-readable twin | https://apps.urthlandscaping.com/handoff.html |

---

*Last verified 2026-08-15. Keep this file and `handoff.html` in step — they are one deliverable
in two formats.*