> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/public-website/src/content/blog/battlefield-cockpit-design.md). # Designing the battlefield without pretending it is omniscient The battlefield model is a product design tool, not a promise that FactionOS has perfect knowledge of every agent action. It gives messy development work a shape that humans can scan: where sessions are, what changed recently, what is blocked, and where review is needed. That distinction matters. The cockpit can make state legible without pretending to be the agent, the terminal, the repository, or a hosted command center. ### Why game language works here Game interfaces are good at showing multiple streams of state without making the player read a log from top to bottom. They use position, status, resources, labels, and event trails to help people decide what needs attention. Agentic development has the same coordination problem. An operator might have a planning session, an implementation session, a validation pass, and a bug hunt running across different tools. A cockpit can turn those fragments into a stable operating view. The [features page](https://github.com/AI-with-Apex-VIP/factionos/tree/main/features/README.md) describes the practical pieces behind that view: session status, review points, local event flow, and evidence that can be read without opening every terminal. ### What the battlefield should show The useful version of the battlefield is concrete: * A session has a name, status, scope, and recent activity. * Work can be grouped by phase, package, route, or task list. * Blocked or failed work is visible instead of buried in scrollback. * Preview panels are labelled so they do not look like connected workspace state. The model should not imply automated execution. It should help a human decide where to look next. ### What stays separate Hosted identity, real executor behavior, remote execution, inbound commands, and erasure policy are separate product and security surfaces that need implementation, tests, documentation, and launch evidence. That is why the [security page](https://github.com/AI-with-Apex-VIP/factionos/tree/main/security/README.md) and the cockpit story need to stay aligned. A more readable interface is useful only if it keeps the boundary between observed local work and unsupported hosted behavior clear. ### The design target The target is not spectacle. The target is a working screen that can survive real development pressure: * An operator can tell which sessions need attention. * A reviewer can see what changed before approving a handoff. * A team can discuss agent work through shared state instead of scattered transcripts. * A future product page can show richer visuals without changing the privacy promise underneath them. That is the role of the battlefield: make agent work visible enough to steer and scoped enough to trust. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/public-website/src/content/blog/battlefield-cockpit-design.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.