docs: align with FTW product vision and ownership

CLAUDE.md

@@ -7,15 +7,34 @@ is the authority and this app is a cached projection of it.
 Read [docs/architecture.md](docs/architecture.md) before changing anything
 structural, and [docs/protocol.md](docs/protocol.md) before touching the wire.
 
+## Shared product direction
+
+Read [FTW's vision](https://github.com/srcfl/ftw/blob/master/VISION.md) and
+[roadmap](https://github.com/srcfl/ftw/blob/master/docs/roadmap.md). Fredrik owns the direction;
+Sourceful develops it. External users submit issues, not pull requests.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+The webapp owns the everyday experience: clear live command/result feedback,
+few routine decisions, direct offline-car SoC entry after connection, persistent
+charging goals, one-action Charge now and notifications when action is needed.
+These are product requirements, not a claim that every flow is complete.
+Preserve expert access and migrate stored settings when simplifying.
+
+Authorized agents are clients of the same Core authority. Support structured
+analysis and intent/result access as the shared contract evolves. Cloud MCP
+is a target: assess reuse of the encrypted session and relay without granting
+the relay plaintext access or bypassing Core validation.
+
 ## The product principle
 
 **Lean, snappy, just works.** This outranks every other preference here, and
 it is a constraint on engineering, not a note for the designer.
 
 - **Nothing blocks the first frame.** Not a network round trip, not a key
   unwrap, not a passkey prompt. The app paints from cache and catches up.
-- **No configuration.** No settings to find, no server to choose, no
-  transport to pick. A question the user cannot answer is the wrong question.
+- **Few required choices.** Discover what the system can know. Keep transport
+  and server choices out of the normal flow. Make household goals easy to set
+  and expert settings available when needed; explain their effect.
 - **Every failure path heals itself if it can.** A dropped connection
   reconnects on its own and shows up only as a freshness stamp falling
   behind. There is no "reconnect" button, and reloading is never the fix.
@@ -113,6 +132,6 @@ change, its tests and a changeset; put the reasoning in the PR description.
 ## Related
 
 - [srcfl/ftw](https://github.com/srcfl/ftw) — the box. Go core, Lua drivers,
-  Python optimizer. Its `AGENTS.md` carries the safety invariants that govern
+  compiled Energyplan worker. Its `AGENTS.md` carries the safety invariants that govern
   anything talking to it.
 - [srcfl/ftw-web](https://github.com/srcfl/ftw-web) — the website.

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to the FTW webapp
+
+Sourceful develops this project. Fredrik owns FTW's product direction in
+[the shared vision](https://github.com/srcfl/ftw/blob/master/VISION.md). External users submit
+[issues](https://github.com/srcfl/ftw-webapp/issues) with bugs, needs and evidence.
+We do not accept external pull requests, including documentation changes.
+Acceptance of an issue does not invite an external implementation PR.
+
+Describe the expected result, what happened, the version and relevant
+hardware. You do not need to write code. Keep credentials, keys and private
+site data out of public reports. Sourceful selects and implements changes.
+
+Existing license rights and copyright attributions remain unchanged.
+Sourceful implementation PRs should state the user need, coordinate overlap,
+include relevant verification and follow the repository's development guide.

README.md

@@ -2,10 +2,22 @@
 
 Your home's energy, from wherever you are.
 
-This is the FTW client — an installable web app that replaces a native mobile
-app. It talks to the FTW box in your home, which is the authority on your
+This is FTW's installable web client. It talks to the FTW box in your home,
+which is the authority on your
 energy system. Sourceful's cloud carries the traffic and cannot read it.
 
+## Product direction and contributions
+
+[The shared FTW vision](https://github.com/srcfl/ftw/blob/master/VISION.md) guides the client:
+fast, honest live feedback; simple daily charging; useful expert access; and
+clear outcomes for both people and authorized agents. The
+[roadmap](https://github.com/srcfl/ftw/blob/master/docs/roadmap.md) states acceptance evidence.
+Goals such as cloud MCP access are distinct from implemented protocol support.
+
+Sourceful maintains the app. External users report needs and bugs through
+[issues](https://github.com/srcfl/ftw-webapp/issues), not PRs.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## The shape of it
 
 ```
@@ -51,14 +63,14 @@ whole database costs a QR scan.
 
 ## Status
 
-Early. The architecture is decided and the protocol is specified; the client
-is being built against a box simulator. See [docs/architecture.md](docs/architecture.md)
-for what was decided and what was rejected, and [docs/protocol.md](docs/protocol.md)
-for the wire contract.
+See [docs/architecture.md](docs/architecture.md) for the architecture and
+[docs/protocol.md](docs/protocol.md) for the wire contract. Some design notes
+record earlier delivery stages; use the current implementation, tests and
+release evidence to establish what a particular box and app support.
+The product vision is a target, not an availability list.
 
-Not yet built: push notifications, the LAN carrier, sharing beyond two roles,
-multi-site. Each is listed with its reason in the architecture doc rather than
-left implied.
+Not yet built: cloud MCP agent access and the WebRTC LAN carrier. The vision
+sets the direction for agent access; the architecture records the LAN work.
 
 ## Running it
 
@@ -67,9 +79,9 @@ npm install
 npm run dev
 ```
 
-The app needs a box to talk to. Until the simulator lands, point it at a local
-FTW with `make dev` in [forty-two-watts](https://github.com/srcfl/ftw) — that
-starts simulated drivers and seeds history, so no hardware is needed.
+For local integration work, run `make dev` in
+[FTW](https://github.com/srcfl/ftw). That starts simulated drivers and seeds
+history, so no hardware is needed.
 
 ```bash
 npm run verify

docs/architecture.md

@@ -3,6 +3,23 @@
 What was decided, what was rejected, and why. Read this before changing
 anything structural.
 
+## Product requirements
+
+Follow [FTW's vision](https://github.com/srcfl/ftw/blob/master/VISION.md). The normal UI should
+show requested intent, Core acceptance, device response, measured effect and
+freshness. Opening after car connection should expose the SoC control without
+extra navigation or a Save step, then show the accepted plan. Keep offline-car
+estimates distinct from readings. Charging failures and goal risks require
+notifications, including when the app is closed.
+
+Agent access is part of the product direction. A cloud MCP endpoint may be an
+authorized client of the box; the relay remains a carrier of encrypted frames.
+An authorized endpoint can read its granted data, so its access must be explicit
+and revocable. Reuse the session where suitable and test Core authorization,
+expiry and outcome reporting. This section adds no operation or grant to the
+current protocol. Retain the difference between persistent schedule changes
+and temporary control that needs renewal.
+
 ## The model
 
 **Edge-authoritative, client-local, cloud-blind.**

docs/protocol.md

@@ -16,6 +16,17 @@ an opinion without both, and the box's CI runs the same comparison the other
 way round. Never hand-write one of those names anywhere else in either
 language.
 
+## Product direction for agent clients
+
+[The shared vision](https://github.com/srcfl/ftw/blob/master/VISION.md) calls for structured
+analysis, durable schedule and goal changes, and proposed-plan submission by
+authorized agents, locally and through cloud MCP. These are targets. They do
+not imply that the operations below already implement them. Extend the registry
+and Core/client implementations together with authorization, expiry, replay,
+revocation and result tests. Core still owns admission and physical dispatch.
+Temporary external control must expire; a saved household goal must survive
+client disconnect. Relay and escrow remain unable to read session contents.
+
 ## Frames
 
 Each Noise transport message carries exactly one frame.