diff --git a/CLAUDE.md b/CLAUDE.md index 40638b4..bdbed93 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,24 @@ 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 @@ -14,8 +32,9 @@ 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a5d880d --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 9bb956b..342ae96 100644 --- a/README.md +++ b/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 diff --git a/docs/architecture.md b/docs/architecture.md index 2872b67..e132a0e 100644 --- a/docs/architecture.md +++ b/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.** diff --git a/docs/protocol.md b/docs/protocol.md index 8165b19..fc50fed 100644 --- a/docs/protocol.md +++ b/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.