Skip to content

README.md

Latest commit

 

History

History
100 lines (85 loc) · 6.3 KB

README.md

File metadata and controls

100 lines (85 loc) · 6.3 KB
Raw

Argos Documentation Index

This document reflects the current code structure as of 2026-07-30. Historical SDDs follow a "keep only active goals" model: shipped implementations retain only maintenance information in current project documentation; one-off spec/plan/tasks process documents are no longer kept.

The current default renderer-main path is typed client / typed event:

Renderer
  -> renderer/api clients
  -> window.argos
  -> shared/contracts/routes + shared/contracts/events
  -> src/main/routes dispatcher
  -> route services / presenter-backed ports
  -> daemon typed routes -> PiProviderExecutionPort -> isolated Pi worker

useLegacyPresenter(), window.electron, and window.api are only allowed inside the src/renderer/api/legacy/** quarantine as compatibility paths. New capabilities for business modules should enter through renderer/api/*Client and shared contracts.

Required Reading

Document Purpose
ARCHITECTURE.md Current main architecture, capability owners, typed boundary rules
FLOWS.md Current messaging, tools, ACP, import, scheduled tasks, and remote control flows
architecture/agent-system.md Pi agent runtime, profiles, packages, tools, and projection flow
architecture/tool-system.md ToolPresenter, agent tools, ACP helper layering
architecture/session-management.md New session management, paginated restore, legacy data plane boundary
architecture/event-system.md Current division of responsibility between EventBus and typed events
guides/code-navigation.md Current code navigation entry point
guides/getting-started.md Quick start for new developers
guides/plugin-packaging.md .dcplugin packaging, built-in distribution, and release rules
guides/remote-machines.md Desktop versus Argos Server, pairing, exposure, lifecycle, and recovery
spec-driven-dev.md SDD directory rules, retention periods, and cleanup rules

Baselines Still In Use At Runtime

Document Purpose
architecture/baselines/dependency-report.md Current dependency and coupling baseline
architecture/baselines/main-kernel-boundary-baseline.md Renderer-main boundary metrics and hot path snapshot
architecture/baselines/main-kernel-bridge-register.md Legacy bridge register
architecture/baselines/main-kernel-migration-scoreboard.md typed-boundary migration scoreboard
architecture/baselines/test-failure-groups.md Test failure grouping baseline

These baselines are generated by scripts/generate-architecture-baseline.mjs, and scripts/architecture-guard.mjs reads the JSON files among them. They are not historical SDDs and should not be deleted together with completed feature documentation.

Current Code Map

docs/
├── README.md
├── ARCHITECTURE.md
├── FLOWS.md
├── release-flow.md
├── spec-driven-dev.md
├── architecture/
│   ├── agent-system.md          ← Pi agent runtime, profiles, packages, tools
│   ├── event-system.md          ← EventBus vs typed events division
│   ├── session-management.md    ← ACP session lifecycle, paginated restore
│   ├── tool-system.md           ← ToolPresenter, agent tools, ACP layering
│   ├── baselines/               ← generated metrics; do not delete
│   ├── agent-scoped-extensions/ ← active: per-agent MCP/skill allowlists
│   ├── argos-connect-relay/     ← active: future relay/cloud design
│   ├── chat-scroll-windowing/   ← active: virtual scroll for large histories
│   ├── electron-vite-to-vite-plugin-electron/ ← active: build toolchain migration
│   ├── extract-ui/              ← active: @argos/ui extraction from desktop
│   ├── memory-subsystem/        ← active: agentic memory / recall subsystem
│   └── tape-subsystem/          ← active: tape manifest integrity and lineage
├── archives/                    ← completed or stale SDD goal folders
├── features/                    ← active feature goals only
│   ├── acp-v1-reliability/
│   ├── agent-state-semantics/
│   ├── daemon-self-update/
│   └── web-folder-picker/
├── issues/
│   └── <recent-active-issue-goal>/
└── guides/
    ├── getting-started.md
    ├── code-navigation.md
    ├── debugging.md
    ├── plugin-packaging.md
    └── remote-machines.md

SDD Retention Rules

  • Goal folders under docs/features/**, docs/issues/**, and docs/architecture/** represent only active goals.
  • For implemented capabilities, fold current maintenance facts into README.md, ARCHITECTURE.md, FLOWS.md, or the corresponding guide, then delete the old SDD folder.
  • Bug-fix issue SDDs are cleaned up after two weeks; as of the current date 2026-07-30, this cleanup cutoff is 2026-07-16.
  • Expired, not-started, or SDDs that only describe removed implementations or old branches are deleted outright.

Suggested Reading Order

  1. Read ARCHITECTURE.md first to build a mental model of the current main flow.
  2. Then read FLOWS.md to see the sequencing for sending messages, tool calls, imports, and remote control.
  3. When diving into the implementation, enter by module:
  4. If you need to understand retired designs, prefer tracing historical commits via git log / git show; do not rely on long-term archived documents in the repository.