> 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/local-first-agent-observability.md). # Local-first agent observability without surprise data paths Agent observability is useful only when it respects the boundary of the work it describes. A coding agent can touch repository paths, shell output, file names, task notes, logs, and prompts. Those signals are valuable to an operator, but they are also context that should not move somewhere else without a clear reason. FactionOS treats that context as local development state first. The [security and privacy page](https://github.com/AI-with-Apex-VIP/factionos/tree/main/security/README.md) uses the same boundary: the product baseline is local-first, and optional hosted surfaces need their own review before they become product defaults. ### Local state is the default The product direction is a local runtime that can ingest and present agent events without requiring an account, hosted database, or analytics provider. The goal is to help the person at the keyboard understand what is happening across sessions while preserving a simple default: the machine running the work is the place where the work is observed. That default matters because agent events are not generic page views. They can describe commands, plans, file operations, and human review decisions. That is also why analytics is not part of the launch site by default. A page view is not worth weakening the product story. If analytics is ever approved, it needs consent, minimization, and documentation that excludes prompts, local paths, replay payloads, and user-provided code. ### Observability should be narrow The useful cockpit view is not a dump of everything an agent sees. It is a curated operational surface: which sessions are active, which tasks changed, which steps are waiting, which errors need attention, and which workflows need a human decision. Keeping that view narrow helps avoid a common failure mode in development tools: collecting broad data because it is convenient, then trying to justify it after the fact. The [features page](https://github.com/AI-with-Apex-VIP/factionos/tree/main/features/README.md) frames this as operational visibility rather than broad capture. The cockpit should show useful state: active work, handoffs, errors, and review points. It should not imply silent tracking, public replay, or hosted storage by default. ### Optional services need explicit contracts Some future integrations may be useful, but they need explicit controls, documented payloads, and local-only fallback behavior. A product page or blog post should not imply that prompts, terminal output, local paths, diagnostics, or replay data are sent to an external system by default. That boundary is part of the product, not a footnote. The public [GitBook documentation](https://faction-os.gitbook.io/faction-os-docs) remains the place for setup and usage details, while this site keeps the product story short and reviewable. ### What this means for publishing Every publishing surface should reinforce the same contract: * Product pages should not ask for prompts, local paths, or code. * External demo and docs links should be named as external destinations. * Hosted identity, erasure policy, and formal certification need separate implementation and review. That keeps the architecture story aligned with the product boundary instead of using marketing copy to race ahead of the system. --- # 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/local-first-agent-observability.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.