docs(portal): session handoff + sub-A IA spec + plan

Captures everything the next Claude session needs to pick up cold:
  - Live module versions on entech (portal 19.0.3.7.0, jobs/reports
    versions, all 5 tests green)
  - What shipped this session (24+ commits, summarised by area)
  - Sub-A (IA + sidebar) brainstorm decisions locked, spec written,
    plan ready to execute (11 tasks, 4 phases)
  - What's deferred (sub-B multi-user, sub-C search, drafts, real
    statements, RMA portal, top-recurring-parts) and WHY — so next
    session doesn't re-litigate
  - Gotchas hit + fixed this session that aren't obvious from code
  - Deploy recipe (file copy + module upgrade + cache bust) used 20+
    times this session

CLAUDE.md's Recent Session Handoff section now points to the new
handoff doc; the previous handoff is kept as 'superseded but kept
for context' below it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

fusion_plating/docs/superpowers/handoffs/2026-05-17-portal-redesign-handoff.md

@@ -0,0 +1,153 @@
+# Portal Redesign — Session Handoff (2026-05-17)
+
+> **Read this first.** This session ran long; the next session picks up here. Everything below is intentionally short. Authoritative details live in the linked spec / plan files.
+
+## TL;DR
+
+Customer-portal redesign across two long sessions. Dashboard + jobs + detail page + configurator are LIVE on entech. The next step (sidebar nav + page audit + Account Summary view) has an APPROVED PLAN ready to execute — do not re-brainstorm, just execute.
+
+**Immediately actionable:** execute [`docs/superpowers/plans/2026-05-17-portal-ia-sidebar-plan.md`](../plans/2026-05-17-portal-ia-sidebar-plan.md) via `superpowers:subagent-driven-development` or `superpowers:executing-plans`. User was offered both at handoff time and chose subagent-driven (preferred). 11 tasks across 4 phases.
+
+## Live state on entech (2026-05-17)
+
+| Module | Version live | Notes |
+|---|---|---|
+| `fusion_plating_portal` | `19.0.3.7.0` | Dashboard, job cards, configurator, detail page, doc downloads, repeat order, animations — all shipped |
+| `fusion_plating_jobs` | `19.0.10.8.0` + write-hook + create-init | fp.job → fp.portal.job state-sync hook on write, initial state derive on create |
+| `fusion_plating_reports` | `19.0.11.15.0` | Customer Acceptance / Authorized Representative signature blocks removed from `report_fp_sale_portrait/landscape` |
+| All 5 portal unit tests green | | `--test-tags=fp_portal` |
+
+Branch: `main`. Local repo is many commits ahead of `origin/main`; user has not been asked to push (per system-prompt safety default). Run `git log --oneline origin/main..HEAD` at session start to see what's outstanding.
+
+## What shipped this session (high-level)
+
+1. **Dashboard rebuild** — `/my/home` → jobs-forward layout (KPI tiles → Active Work Orders hero → 5 secondary panels). Welcome line summarises status in plain words. EN Plating teal brand palette with gradient CTAs.
+2. **Job card upgrade** — shared `fp_portal_job_card` macro (used by `/my/home` + `/my/jobs`). Wrap div + inner anchor + sibling actions footer (4 doc download chips + Repeat Order POST form). Part info + ship-to address pulled inline. Pulse animation on the active step circle + matching detail-page timeline dot.
+3. **Detail page** — V2 stepper + V3 timestamps + 5-group document panel (From You / Specifications / Work Order / Quality / Shipping). Sales Order Confirmation, Work Order Detail, CoC, Packing Slip all sudo-render from the FP custom reports. Hero shows part + ship-to.
+4. **Configurator fixes** — `/my/configurator/coating` 500 fixed (`fp.coating.config` → `fusion.plating.process.type`). Manual measurements hidden in step 1. Split single-file upload into Drawing (PDF) + 3D Model.
+5. **Sale report cleanup** — Customer Acceptance / Authorized Representative signature block removed.
+6. **Misc** — `/my` route added, button sizing normalised, hover-underline suppressed globally, sidebar of legacy stuff redirected, dashboard expanded to 5 panels (Quote Requests + Purchase Orders added).
+
+24+ commits this session, all on `main`. Browse `git log --oneline -30` for the full sweep.
+
+## What's queued for execution
+
+**Sub-A (Portal IA + Sidebar):** plan ready, not yet executed. Brainstorm decisions baked in:
+
+| Decision | Choice |
+|---|---|
+| Sidebar shape | **B** — Dashboard top, then grouped Activity / Documents / Account sections |
+| Account Summary tabs | 3 (Invoices / Credit Memos / Statements) + Open Balance pill in header |
+| Statements V1 | Placeholder card ("Coming soon") — real statement generation deferred |
+| Legacy URL redirects | `/my/fp_invoices` → `/my/account_summary`; `/my/purchase_orders` → `/my/orders` (Odoo default); `/my/quote_requests/new` GET → `/my/configurator/new` |
+| Future Users / Search slots | Omit from V1 (no "coming soon" placeholders); add when sub-B/sub-C ship |
+
+Spec: [`docs/superpowers/specs/2026-05-17-portal-ia-sidebar-design.md`](../specs/2026-05-17-portal-ia-sidebar-design.md)
+
+## What's deferred (do NOT re-litigate in next session)
+
+These were explicitly scoped OUT during brainstorming. Open new brainstorm sessions for each when their turn comes:
+
+- **Sub-B Multi-user account management** — invite teammates, role per user, per-action ACLs. Will add a Users item under the Account section of the sidebar.
+- **Sub-C Portal search** — global search across jobs / quotes / invoices / certs. Search input slot above Dashboard in the sidebar.
+- **Saved drafts (RFQ)** — user mentioned wanting drafts during configurator. Three scoping options proposed (minimal/medium/big); awaiting user direction. Not part of sub-A.
+- **Real Statements generation** — account.followup integration OR cron-precomputed monthly PDFs. Decide during sub-A Phase 3 implementation or defer to its own follow-up.
+- **Top Recurring Parts / Favorites / SerialNumber Lookup** — competitor-style features; deferred until customer demand confirmed.
+- **RMA customer portal** — sub-12 RMA backend exists; portal exposure is its own sub-project.
+
+## Gotchas that bit us this session
+
+Future Claude will hit these too unless documented. Most are already inline in CLAUDE.md or MEMORY.md. Worth a re-skim before touching the portal:
+
+1. **`fp.coating.config` is retired** (Sub-11 cleanup). Use `fusion.plating.process.type` as the customer-facing coating taxonomy. Multiple `*.py` files still reference the dead model in COMMENTS — don't pattern-match from those.
+2. **Portal users can't read `fp.job` directly.** Controllers that return `fp.portal.job` records to a template MUST `sudo()` the search if the template traverses `job.x_fc_job_id`. Same pattern is already used for `sale.order`, `account.move`, `stock.picking`. Domain still filters to commercial partner tree.
+3. **`sale_pdf_quote_builder` gates on `report_name == 'sale.report_saleorder'`** (already in MEMORY.md). For customer-facing SO PDFs on the portal, render the FP custom `fusion_plating_reports.report_fp_sale_portrait` instead, and use a dedicated portal route that sudo-renders so the QWeb template can walk into `fp.part.catalog` etc.
+4. **Forms inside anchors is invalid HTML.** When making a whole card clickable AND embedding a Repeat-Order form inside, use a wrap div + inner anchor (main click target) + sibling actions footer (form lives here). Don't nest `<form>` inside `<a>`.
+5. **Groups list indexing drift.** `_fp_group_documents` builds the docs panel by appending to `groups[N]`. If you reorder the initial list or insert a new group mid-helper, every `groups[N]` reference shifts. The code has an inline warning comment now; respect it.
+6. **Per-stage timestamps are NULL on records created before the write hook deployed.** `_fp_get_stage_timeline` has a Date-fallback chain (received_date → received_at; actual_ship_date → shipped_at) plus linear interpolation for middle stages. Records created post-hook get real datetimes from the `fp.job.write()` mirror.
+7. **Stepper SCSS — `.o_fp_step_line` MUST stay nested inside `.o_fp_stepper`** (inline comment in the SCSS warns about this). When `flex:1` isn't applied because the rule slipped outside the parent, circles cluster on the left of the row.
+8. **Stepper labels align via absolute positioning per-unit** (not as a separate flex container). Wider labels like "Inspected" overflow equally to both sides of their circle's centre. Don't revert to the dual-container approach.
+9. **`fp.portal.job` state-sync map** uses `_FP_JOB_STATE_TO_PORTAL_STATE` in `fusion_plating_jobs/models/fp_job.py`. `on_hold` and `cancelled` deliberately NOT mirrored to the customer-facing state. Manager decision what to surface.
+
+## How to deploy (entech LXC 111 on pve-worker5)
+
+Same recipe used 20+ times this session. Per file:
+
+```bash
+cat K:/Github/Odoo-Modules/fusion_plating/<module>/<path> | \
+  ssh pve-worker5 "pct exec 111 -- bash -c 'cat > /mnt/extra-addons/custom/<module>/<path>'"
+```
+
+Then upgrade module + run tests:
+
+```bash
+ssh pve-worker5 "pct exec 111 -- bash -c 'systemctl stop odoo && \
+  su - odoo -s /bin/bash -c \"/usr/bin/odoo -c /etc/odoo/odoo.conf -d admin \
+    -u fusion_plating_portal --test-tags=fp_portal --stop-after-init 2>&1 | tail -25\" && \
+  systemctl start odoo'"
+```
+
+Bust asset cache for SCSS/JS changes:
+
+```bash
+ssh pve-worker5 "pct exec 111 -- su - postgres -c \
+  \"psql -d admin -c \\\"DELETE FROM ir_attachment WHERE url LIKE '/web/assets/%';\\\"\""
+```
+
+Service status / version check:
+
+```bash
+ssh pve-worker5 "pct exec 111 -- bash -c 'systemctl is-active odoo'"
+ssh pve-worker5 "pct exec 111 -- su - postgres -c \
+  \"psql -d admin -t -c \\\"SELECT latest_version FROM ir_module_module \
+    WHERE name='fusion_plating_portal';\\\"\""
+```
+
+## How to start the next session
+
+1. Open Claude Code in `K:\Github\Odoo-Modules\fusion-plating` (or `K:\Github\Odoo-Modules\fusion_plating` — both work, the dash dir has only 3 modules but it's the active working dir for the user's terminal).
+2. First message: "Resume the portal sub-A IA work — execute the approved plan from this session."
+3. New session should:
+   - Read `CLAUDE.md` (auto-loaded) — the "Recent Session Handoff" section at the top points back to this file
+   - Read this handoff doc
+   - Read the plan: `docs/superpowers/plans/2026-05-17-portal-ia-sidebar-plan.md`
+   - Invoke `superpowers:subagent-driven-development` (or `executing-plans` for inline mode)
+   - Execute the 11 tasks across 4 phases
+4. Optional but useful: re-run the existing test suite first to confirm starting from green: `--test-tags=fp_portal --stop-after-init`.
+
+## Brainstorm artifacts
+
+Visual companion mockups for this session live in `.superpowers/brainstorm/*/content/` (gitignored). Useful for visual comparison if needed:
+- `design-direction.html` — Modern SaaS / Corporate / Industrial picker
+- `saas-refinements.html` — V1/V2/V3 card variants
+- `dashboard-layout.html` — 6-card grid vs jobs-forward
+- `job-detail.html`, `branded-job-detail.html` — detail page mockups
+- `branded-dashboard.html` — final brand-applied dashboard
+- `sidebar-structure.html` — flat vs grouped vs hybrid (chose grouped)
+
+Brainstorm server idles out after 30 min. Restart command:
+
+```bash
+"C:/Users/gur_p/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.7/skills/brainstorming/scripts/start-server.sh" \
+  --project-dir "K:/Github/Odoo-Modules/fusion_plating"
+```
+
+(Run in background; URL appears in `.superpowers/brainstorm/*/state/server-info`.)
+
+## Critical files modified this session
+
+If the next session needs to read context fast:
+- `fusion_plating_portal/controllers/portal.py` — most changes here
+- `fusion_plating_portal/controllers/portal_configurator.py` — coating model swap + dual upload
+- `fusion_plating_portal/views/fp_portal_dashboard.xml` — jobs-forward layout
+- `fusion_plating_portal/views/fp_portal_templates.xml` — jobs list + detail rewrites
+- `fusion_plating_portal/views/fp_portal_macros.xml` — `fp_portal_job_card`, `fp_portal_stepper`, `fp_portal_status_badge`, `fp_portal_doc_chip`, `fp_portal_doc_group`
+- `fusion_plating_portal/static/src/scss/_fp_portal_tokens.scss` — brand tokens
+- `fusion_plating_portal/static/src/scss/fp_portal_*.scss` — 7 partials (buttons, badges, cards, stepper, timeline, dashboard, legacy catch-all)
+- `fusion_plating_portal/models/fp_portal_job.py` — per-stage Datetime fields + write/create snapshot hooks
+- `fusion_plating_jobs/models/fp_job.py` — fp.job → fp.portal.job state-sync hook
+- `fusion_plating_portal/tests/test_portal_dashboard.py` — 5 tests, all green
+
+## What user feedback is still outstanding
+
+Nothing concrete waiting on user. Last thing the user did was approve the plan and say "create a handsoff script so i start a new session" — i.e., they want to pause here. Next session resumes execution.