docs: present FlipCTL architecture proposal and evolution path

[blockedby]

Why

The FlipCTL brief asks for a concrete architecture, a plugin/wrapper vision, and a working prototype that drives both Web and TUI frontends.

This PR presents the repository as one implementation proposal without treating every prototype choice as final.

Proposed architecture

• A small Go daemon owns applications, frontend sessions, shared jobs, events, and command execution.
• A versioned semantic ViewDocument separates application state from renderer implementation.
• Web and TUI render the same meaning using platform-native controls.
• Declarative command apps provide the initial Ping and Nmap plugin tier.
• A 256×144 Canvas renderer demonstrates adaptation to the Flipper One display constraints.
• Docker and ARM64 userspace checks prove the main flow without claiming hardware emulation.

What the prototype demonstrates

1. Web and TUI create independent sessions.
2. A job started from one frontend becomes visible in the other.
3. The second frontend can cancel the shared job.
4. Both frontends update from the same daemon-owned state.
5. The returned semantic views validate against one strict schema.

Deliberate tradeoffs

The MVP favors architectural clarity over feature breadth:

• declarative apps before arbitrary executable plugins;
• in-memory sessions/jobs before persistence;
• browser-native HTTP/SSE before a compact device protocol;
• a Canvas renderer preview before final DRM/MCU integration;
• userspace Docker/QEMU proof before physical hardware claims.

The accompanying decisions document records when and how these choices should be revisited.

Documents

• README.md — concise introduction and proof
• docs/architecture.md — proposed component model and interactions
• docs/decisions-and-roadmap.md — tradeoffs, ownership handoffs, and future decision gates
• docs/view-document.md — machine-facing semantic contract details

Review focus

Feedback is especially welcome on:

• the daemon/session/job ownership model;
• the semantic block vocabulary;
• the boundary between declarative apps and future native plugins;
• the appropriate first hardware/display integration lane;
• which decisions should be frozen now versus deferred.

Validation

The repository includes contract and renderer tests, a two-session architecture acceptance test, Web and TUI tests/builds, Docker fake-command smoke, and ARM64 userspace smoke.

No physical Flipper One hardware validation is claimed.

[zhovner]

Thanks, I’ll take a look and get back to you soon.