docs: move the engineering documents into docs/

Thirteen files at the repository root, seven of them documents. Only README.md
earns a place there; the rest are now in docs/ beside the meeting notes, the
client roadmap and the historical material.

The compose files stay. docker-compose.yml is the path the dtf-cloud Portainer
stack reads, so moving it would break deployment, and Docker resolves a compose
file's relative build contexts against its own directory, so moving the other
two would silently break every build. Both reasons are now written down where
someone would otherwise try it.

Correcting references turned up a live fault: the Portainer stack creation
instructions still named deploy/stack.yaml as the compose path. That file was
removed, so anyone recreating the stack from these instructions would have
failed. It names docker-compose.yml now, with the reason it stays at the root.

ROADMAP.md keeps the paths its closed findings were written with, and says so at
the top. Those entries record where a fault was when it was found; rewriting
them to match a later layout would make the record less true, not more.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitea/workflows/deploy.yml

@@ -145,7 +145,7 @@ jobs:
             fs --scanners secret --exit-code 1 --severity HIGH,CRITICAL \
             --no-progress /src
 
-      # PORTAINER.md described this as blocking publication. It never ran at
+      # docs/PORTAINER.md described this as blocking publication. It never ran at
       # all, and turning it on unconditionally would block every deploy: the
       # source preflight refuses a release while the payment and messaging
       # adapters are fake, which is the deliberate state the stack runs in

README.md

@@ -1,12 +1,12 @@
 # Sistema DTF 24h — Altus Group
 
-> **Active local milestone (2026-09-11):** Read [CONTEXT.md](CONTEXT.md) first.
+> **Active local milestone (2026-09-11):** Read [docs/CONTEXT.md](docs/CONTEXT.md) first.
 > Start with `docker compose up --build`, then open the [Site](http://localhost:8080)
 > and [Kanban](http://localhost:8081). Optional configuration: copy `.env.example`
-> to `.env`. Follow [LOCAL_SETUP.md](LOCAL_SETUP.md) for the complete test flow,
+> to `.env`. Follow [docs/LOCAL_SETUP.md](docs/LOCAL_SETUP.md) for the complete test flow,
 > local login, health checks, and troubleshooting. See
-> [IMPLEMENTATION_REPORT.md](IMPLEMENTATION_REPORT.md) for scope and reuse decisions.
+> [IMPLEMENTATION_REPORT.md](docs/historico/IMPLEMENTATION_REPORT.md) for scope and reuse decisions.
-> Production delivery uses one Portainer stack; see [PORTAINER.md](PORTAINER.md).
+> Production delivery uses one Portainer stack; see [docs/PORTAINER.md](docs/PORTAINER.md).
 > Everything below is preserved historical prototype documentation, not the active
 > setup or delivery specification. Do not run its production integrations or agent.
 
@@ -20,8 +20,8 @@
 > `schema.sql`, `.env.exemplo`) no longer exists, and the model it describes is
 > not the one implemented. Kept for the business reasoning in it — the capacity
 > figures, the cost argument, the meeting decisions. For how the system actually
-> works read [CONTEXT.md](CONTEXT.md); for what is outstanding read
+> works read [docs/CONTEXT.md](docs/CONTEXT.md); for what is outstanding read
-> [ROADMAP.md](ROADMAP.md); for the original documents see
+> [docs/ROADMAP.md](docs/ROADMAP.md); for the original documents see
 > [docs/historico/](docs/historico/README.md).
 
 ---

app/core/secrets.py

@@ -3,7 +3,7 @@
 Swarm mounts each secret as a file and the stack passes its path as `<NAME>_FILE`.
 The deployed `docker-compose.yml` passes credentials as plain environment
 variables, so this module is inert there. It exists so a stack can supply them as
-Docker secrets instead without any code change; see `ROADMAP.md` 2.12.
+Docker secrets instead without any code change; see `docs/ROADMAP.md` 2.12.
 
 Call `load()` in every entrypoint before any configuration is read.
 

deploy/PRODUCTION_CHECKLIST.md

@@ -5,7 +5,7 @@ substitute for `production_preflight.py`, CI, staging acceptance, or change appr
 
 ## Application and external contracts
 
-- [ ] `PRODUCTION_INPUTS.md` has owners, decisions, and evidence for every item.
+- [ ] `docs/PRODUCTION_INPUTS.md` has owners, decisions, and evidence for every item.
 - [ ] Production R2, freight, Mercado Pago, Tiny/Olist, and WhatsApp adapters have
       sandbox contract tests and least-privilege credentials.
 - [ ] Payment webhook authenticity, replay handling, and idempotency are tested.

docs/CONTEXT.md

@@ -141,7 +141,7 @@ taxes, and payment-provider fees before presenting a commercial quote.
 
 ## Commercial rules
 
-The existing rules in `dtf-site.html` are approved as the current source of
+The existing rules in `web/index.html` are approved as the current source of
 truth. Do **not** redesign, simplify, or change prices, discounts, minimums,
 rounding, or product modes without explicit approval.
 
@@ -163,7 +163,7 @@ image dimensions alone must never classify a normal artwork as a finished sheet.
 
 ## Freight
 
-The original visual freight flow in `dtf-site.html` was a stub with only pickup
+The original visual freight flow in `web/index.html` was a stub with only pickup
 functional. The localhost bridge now supports pickup and backend fake freight
 quotes; there is still no real carrier quotation or production checkout.
 
@@ -313,7 +313,7 @@ as references and are not imported or started by Compose.
 - All direct and transitive Python packages are pinned with artifact hashes in
   `infra/requirements.lock`; the API image build requires those hashes. The lock
   is regenerated in a disposable Python 3.12 container by
-  `local/lock_dependencies.sh`. A fresh exact-runtime audit found no known Python
+  `infra/lock_dependencies.sh`. A fresh exact-runtime audit found no known Python
   advisories on 2026-09-15; this does not cover OS/container findings.
 - `compose.staging.yaml` is a separate, network-disabled readiness gate only. It
   validates non-secret staging decisions and rejects placeholders, local endpoints,
@@ -373,7 +373,7 @@ referenced them; recover from Git history if ever needed.
   recovery, and cross-device cart editing are still absent.
 - Without the local bridge, the original freight fallback remains a stub.
   Real freight quotation remains unimplemented in all runtimes.
-- The existing `portal/whats.py` and `kanban/whats.py` are duplicated and send
+- The existing the removed prototypes duplicated WhatsApp senders and send
   direct text messages. They are not production-ready notification modules.
 - Older documentation and code describe a Tiny webhook creating an upload link,
   a factory agent, local Kanban, FlexiPRINT automation, 90-day retention, and

docs/PORTAINER.md

@@ -5,12 +5,11 @@ prebuilt images, pushes them to the Gitea registry, and calls one Portainer
 webhook. Portainer owns and redeploys one Docker Swarm stack named `dtf-cloud`.
 
 The deployed stack is the repository's `docker-compose.yml`, which the
-`dtf-cloud` Portainer stack points at. `deploy/stack.yaml` is a more hardened
+`dtf-cloud` Portainer stack points at. It was once accompanied by `deploy/stack.yaml`, a more hardened definition
-definition that supplies every credential as a Docker secret rather than an
+supplying credentials as Docker secrets; that file was removed in favour of one
-environment variable; it is not currently deployed. See `ROADMAP.md` 2.12 before
+definition. See `ROADMAP.md` 2.12 for the reasoning and what remains open.
-assuming either is authoritative.
 
-`deploy/stack.yaml` contains Site, Kanban, API,
+The stack contains Site, Kanban, API,
 worker, PostgreSQL, ClamAV, and a one-time database initializer. Production uses
 Cloudflare R2, so MinIO is not part of this stack.
 
@@ -94,7 +93,8 @@ In Portainer select **Stacks → Add stack → Git repository**:
 - Name: `dtf-cloud`
 - Repository: this Gitea repository
 - Reference: `main`
-- Compose path: `deploy/stack.yaml`
+- Compose path: `docker-compose.yml` (the repository default, which is what the
+  existing `dtf-cloud` stack uses; it must stay at the root for this reason)
 - Registry: the private `gitea.blyzer.com.br` registry
 - Re-pull image: enabled
 - Automatic update: webhook

docs/ROADMAP.md

@@ -12,6 +12,11 @@
 client inputs (1.1, 1.2, 2.10). Block 1 still waits on client inputs for
 1.1/1.2.
 
+> Paths in closed items are written as they were when the finding was made.
+> The repository was laid out by role on 2026-09-21 (`local/` became `app/`,
+> with `tests/`, `ops/`, `infra/` and `web/` beside it); the history is left
+> as recorded rather than rewritten.
+
 **Last audit:** 2026-09-18, full read of `app/`, `dtf-site.html`, `deploy/`,
 `.gitea/`, docs and legacy prototypes. Findings below carry their audit IDs.
 

staging/README.md

@@ -2,9 +2,9 @@
 
 This directory does not contain a staging deployment and does not authorize any
 real integration. It provides a separate, network-disabled validation root for
-the non-secret decisions in `PRODUCTION_INPUTS.md`.
+the non-secret decisions in `docs/PRODUCTION_INPUTS.md`.
 
-1. Complete the business and technical decisions in `PRODUCTION_INPUTS.md`.
+1. Complete the business and technical decisions in `docs/PRODUCTION_INPUTS.md`.
 2. Copy `staging.env.example` to `staging.env` and replace the `TBD` values with
    non-secret metadata only. `staging.env` is ignored by Git and Docker builds.
 3. Run: