diff --git a/.agents/journal/scribe-journal.md b/.agents/journal/scribe-journal.md index 634758280..e815975c2 100644 --- a/.agents/journal/scribe-journal.md +++ b/.agents/journal/scribe-journal.md @@ -70,6 +70,54 @@ --- +## 2026-03-04 - Codecov Web Configuration - COMPLETE + +- Configured Vitest coverage in `clients/web/apps/chat` and `clients/web/apps/dashboard` using `v8` provider. +- Added `test:coverage` script to `package.json` of these apps. +- Updated `.github/codecov.yml` with flags for `rust`, `kotlin`, and `web`. +- Extended the Gradle build in `clients/web/build.gradle.kts` to include an aggregate task `testCoverageAllWebApps`. +- Updated `.github/workflows/pull-request-check.yml` to execute web coverage tests and upload `lcov.info` files to Codecov. +- Standardized `@vitest/coverage-v8` version in `clients/web/pnpm-workspace.yaml` catalog. + +- Optimized Gradle web tasks to be configuration-cache compliant by deferring package.json script checks to execution time using `onlyIf`. +- Improved Codecov reliability in CI by using `directory` parameter for web coverage uploads, ensuring all `lcov.info` files are discovered without relying on runner-side glob expansion. + +- Pinned C4-PlantUML include to v2.13.0 for documentation stability. +- Localized actor labels in Spanish container diagrams. +- Corrected GPG setup documentation regarding key sizes and CI/CD subkey export commands. +- Added language tags to PGP blocks in Spanish documentation to satisfy linting. + +--- + +## 2026-03-06 - Documentation Review & Sync - COMPLETE + +**Verification:** +- Audited `clients/agent-runtime/src/lib.rs` and `main.rs` against CLI docs. +- Discovered missing `update` command in CLI reference. +- Identified generic/outdated content in `intro/introduction.mdx`. +- Verified `make` commands in root `README.md` were incorrect (`docs-web-build` vs `docs-build`). +- Confirmed `guides/structure.md` and `guides/getting-started.md` are accurate. + +**Changes:** +- **CLI Reference (en/es):** + - Added full `update` command section. + - Refined `peripheral flash` to include `-p/--port`. +- **Introduction (en/es):** + - Replaced generic placeholder text with detailed project info from root README. + - Fixed image asset path by creating `clients/web/apps/docs/src/assets/` and copying `corvus.png`. +- **Root README:** + - Corrected documentation build commands to `make docs-build` and `make docs-dev`. + +**Validation:** +- ✅ `make docs-check`: Passed. +- ✅ `make docs-build`: Passed (after fixing image path). + +**Notes:** +- Architecture guides are split into `architecture.md` (Overview) and `architecture/overview.md` (Diagrams Index). This is functional but slightly confusing in structure. +- `architecture/overview.md` is orphaned from the sidebar but reachable via links. + +--- + ## 2026-05-22 - CLI Reference Audit & Update - COMPLETE **Verification:** @@ -101,20 +149,3 @@ - [ ] Consider CSS !important warnings (optional, may need Biome config) - [x] Update CLI docs with missing subcommands (high priority) - DONE (both en/es) - [x] Audit and document missing CLI flags/commands from agent-runtime - DONE - -## Codecov Web Configuration (2026-03-04) - -- Configured Vitest coverage in `clients/web/apps/chat` and `clients/web/apps/dashboard` using `v8` provider. -- Added `test:coverage` script to `package.json` of these apps. -- Updated `.github/codecov.yml` with flags for `rust`, `kotlin`, and `web`. -- Extended the Gradle build in `clients/web/build.gradle.kts` to include an aggregate task `testCoverageAllWebApps`. -- Updated `.github/workflows/pull-request-check.yml` to execute web coverage tests and upload `lcov.info` files to Codecov. -- Standardized `@vitest/coverage-v8` version in `clients/web/pnpm-workspace.yaml` catalog. - -- Optimized Gradle web tasks to be configuration-cache compliant by deferring package.json script checks to execution time using `onlyIf`. -- Improved Codecov reliability in CI by using `directory` parameter for web coverage uploads, ensuring all `lcov.info` files are discovered without relying on runner-side glob expansion. - -- Pinned C4-PlantUML include to v2.13.0 for documentation stability. -- Localized actor labels in Spanish container diagrams. -- Corrected GPG setup documentation regarding key sizes and CI/CD subkey export commands. -- Added language tags to PGP blocks in Spanish documentation to satisfy linting. diff --git a/README.md b/README.md index f5f408f2c..96ee32467 100644 --- a/README.md +++ b/README.md @@ -178,8 +178,8 @@ make dev-down # Stop the environment Detailed documentation is available in the `clients/web/apps/docs/` directory. You can build and view it locally: ```bash -make docs-web-build -make docs-web-dev +make docs-build +make docs-dev ``` --- diff --git a/clients/web/apps/docs/src/assets/corvus.png b/clients/web/apps/docs/src/assets/corvus.png new file mode 100644 index 000000000..e9eb0f2ed Binary files /dev/null and b/clients/web/apps/docs/src/assets/corvus.png differ diff --git a/clients/web/apps/docs/src/content/docs/en/guides/cli-reference.md b/clients/web/apps/docs/src/content/docs/en/guides/cli-reference.md index fc85ee98e..25be66871 100644 --- a/clients/web/apps/docs/src/content/docs/en/guides/cli-reference.md +++ b/clients/web/apps/docs/src/content/docs/en/guides/cli-reference.md @@ -300,6 +300,7 @@ Manage hardware peripherals (STM32, RPi, etc.). - `add `: Add a peripheral. - `flash-nucleo`: Flash Corvus firmware to Nucleo-F401RE. - `flash`: Flash Corvus firmware to Arduino. + - `-p, --port `: Serial port (if omitted, uses first arduino-uno from config). - `setup-uno-q`: Setup Arduino Uno Q Bridge app (deploy GPIO bridge). - `--host `: Uno Q IP address. @@ -326,3 +327,21 @@ Migrate data from other agent runtimes. ```bash corvus migrate openclaw --source ~/.openclaw/workspace ``` + +### `update` + +Manage runtime updates. + +- `status`: Show update status and effective policy. +- `check`: Force an update check. +- `install`: Run update install transaction. +- `auto-enable`: Enable auto-install policy. +- `auto-disable`: Disable auto-install policy. +- `history`: Show update audit history. +- `confirm `: Confirm a one-time update confirmation nonce. + +**Example:** + +```bash +corvus update check +``` diff --git a/clients/web/apps/docs/src/content/docs/en/intro/introduction.mdx b/clients/web/apps/docs/src/content/docs/en/intro/introduction.mdx index 5a6aa601e..410a80dda 100644 --- a/clients/web/apps/docs/src/content/docs/en/intro/introduction.mdx +++ b/clients/web/apps/docs/src/content/docs/en/intro/introduction.mdx @@ -1,27 +1,55 @@ --- title: Introduction +description: Welcome to the Corvus Agent Platform documentation. --- # Welcome to Corvus -Corvus is a powerful, modular system designed for building scalable applications. This documentation will help you understand, install, and use its core capabilities effectively. +**Corvus** is a highly extensible, multi-interface agentic platform designed to bridge the gap between AI autonomy and human supervision. Built with a robust **Kotlin Multiplatform** foundation and powered by a high-performance **Rust** runtime, Corvus provides a secure, sandboxed environment for AI agents to perform complex, multi-step tasks. -## Key Features +![Corvus Architecture](../../../../assets/corvus.png) -- **Modular Design:** Easily configurable and scalable. -- **Security-First Approach:** Built with secure defaults and best practices. -- **Cross-Platform:** Supports Android, iOS, Desktop, and Web setups. +## ✨ Features -## Getting Started +- **Multi-Interface Support**: Interact with Corvus via CLI, a Compose Multiplatform Desktop app, or a web-based dashboard. +- **Always-On Autonomy**: A daemon mode for long-running agents that can handle background tasks and persistent orchestration. +- **Secure Sandboxing**: Execute dangerous commands safely within isolated Docker containers or restricted native runtimes. +- **Standardized Identity (AIEOS)**: Support for AIEOS v1.1, allowing for portable and model-agnostic AI personas. +- **Hybrid Memory Model**: Pluggable memory backends including SQLite, Neo4j, and SurrealDB for high-context retrieval. +- **Rich Integrations**: First-class support for WhatsApp (via Meta Cloud API), git, npm, cargo, and more. -- **Setup Instructions:** Follow the [Getting Started](../guides/getting-started/) guide to set up the project. -- **Architecture Overview:** Understand the [system architecture](../guides/architecture/). -- **Feature Overview:** Explore the [features](../guides/features/). +## 🛠️ Tech Stack + +- **Core Logic**: [Kotlin Multiplatform (KMP)](https://kotlinlang.org/docs/multiplatform.html) +- **Agent Runtime**: [Rust](https://www.rust-lang.org/) (High-performance sidecars and CLI) +- **Desktop UI**: [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/) +- **Web Stack**: [Astro](https://astro.build/), [Vue 3](https://vuejs.org/), and [Tailwind CSS](https://tailwindcss.com/docs) +- **Documentation**: [Starlight](https://starlight.astro.build/) +- **Build System**: [Gradle](https://gradle.org/) & [Makefile](https://www.gnu.org/software/make/) + +## 📂 Project Structure + +This repository is organized as a monorepo: + +```text +corvus/ +├── clients/ +│ ├── agent-runtime/ # High-performance Rust Agent Core & CLI +│ ├── composeApp/ # Shared UI logic for Desktop/Mobile +│ ├── web/ # Web monorepo (Docs, Dashboard, Marketing) +│ ├── androidApp/ # Android specific wrapper +│ └── iosApp/ # iOS specific wrapper +├── modules/ +│ └── agent-core-kmp/ # Core Kotlin Multiplatform logic & contracts +├── dev/ # Local development environment (Docker/Sandbox) +├── gradle/ # Build logic and configurations +└── Makefile # Standard entry point for development tasks +``` ## Next Steps -Dive deeper into: +Ready to get started? -- [Configuration and Customization](../guides/configuration/) -- [Development Workflow](../guides/development/) -- [Release Process](../guides/release/) \ No newline at end of file +- **[Getting Started](../guides/getting-started/)**: Install and run your first agent. +- **[CLI Reference](../guides/cli-reference/)**: Master the command line interface. +- **[Architecture](../guides/architecture/)**: Understand the system design. \ No newline at end of file diff --git a/clients/web/apps/docs/src/content/docs/es/guides/cli-reference.md b/clients/web/apps/docs/src/content/docs/es/guides/cli-reference.md index 00be83c45..847001c2a 100644 --- a/clients/web/apps/docs/src/content/docs/es/guides/cli-reference.md +++ b/clients/web/apps/docs/src/content/docs/es/guides/cli-reference.md @@ -267,6 +267,7 @@ Gestiona periféricos de hardware (STM32, RPi, etc.). - `add `: Añade un periférico. - `flash-nucleo`: Flashea el firmware de Corvus al Nucleo-F401RE. - `flash`: Flashea el firmware de Corvus al Arduino. + - `-p, --port `: Puerto serie (si se omite, usa el primer arduino-uno de la configuración). - `setup-uno-q`: Configura la aplicación Arduino Uno Q Bridge (despliega bridge GPIO). - `--host `: Dirección IP de Uno Q. @@ -293,3 +294,21 @@ Migra datos desde otros runtimes de agentes. ```bash corvus migrate openclaw --source ~/.openclaw/workspace ``` + +### `update` + +Administrar actualizaciones del runtime. + +- `status`: Mostrar estado de actualización y política efectiva. +- `check`: Forzar una comprobación de actualización. +- `install`: Ejecutar transacción de instalación de actualización. +- `auto-enable`: Habilitar política de instalación automática. +- `auto-disable`: Deshabilitar política de instalación automática. +- `history`: Mostrar historial de auditoría de actualizaciones. +- `confirm `: Confirmar un nonce de confirmación de actualización de uso único. + +**Ejemplo:** + +```bash +corvus update check +``` diff --git a/clients/web/apps/docs/src/content/docs/es/intro/introduction.mdx b/clients/web/apps/docs/src/content/docs/es/intro/introduction.mdx index ea34a1ac1..79e445e47 100644 --- a/clients/web/apps/docs/src/content/docs/es/intro/introduction.mdx +++ b/clients/web/apps/docs/src/content/docs/es/intro/introduction.mdx @@ -1,27 +1,55 @@ --- title: Introducción +description: Bienvenido a la documentación de la Plataforma de Agentes Corvus. --- # Bienvenido a Corvus -Corvus es un sistema modular y potente diseñado para construir aplicaciones escalables. Esta documentación te ayudará a comprender, instalar y usar sus capacidades principales de manera efectiva. +**Corvus** es una plataforma agéntica altamente extensible y multi-interfaz diseñada para cerrar la brecha entre la autonomía de la IA y la supervisión humana. Construida con una base robusta en **Kotlin Multiplatform** e impulsada por un runtime de alto rendimiento en **Rust**, Corvus proporciona un entorno seguro y aislado (sandboxed) para que los agentes de IA realicen tareas complejas de múltiples pasos. -## Características Clave +![Arquitectura de Corvus](../../../../assets/corvus.png) -- **Diseño Modular:** Fácilmente configurable y escalable. -- **Enfoque de Seguridad Primero:** Construido con configuraciones seguras y buenas prácticas. -- **Multiplataforma:** Compatible con Android, iOS, Escritorio y Web. +## ✨ Características -## Primeros Pasos +- **Soporte Multi-Interfaz**: Interactúa con Corvus a través de la CLI, una aplicación de escritorio Compose Multiplatform o un panel de control web. +- **Autonomía Siempre Activa**: Un modo demonio para agentes de larga duración que pueden manejar tareas en segundo plano y orquestación persistente. +- **Sandboxing Seguro**: Ejecuta comandos peligrosos de forma segura dentro de contenedores Docker aislados o runtimes nativos restringidos. +- **Identidad Estandarizada (AIEOS)**: Soporte para AIEOS v1.1, permitiendo personas de IA portátiles y agnósticas al modelo. +- **Modelo de Memoria Híbrido**: Backends de memoria conectables, incluyendo SQLite, Neo4j y SurrealDB para recuperación de alto contexto. +- **Integraciones Ricas**: Soporte de primera clase para WhatsApp (vía Meta Cloud API), git, npm, cargo y más. -- **Instrucciones de Configuración:** Sigue la guía de [Primeros Pasos](../guides/getting-started/) para configurar el proyecto. -- **Resumen de Arquitectura:** Comprende la [arquitectura del sistema](../guides/architecture/). -- **Descripción de Funcionalidades:** Explora las [funcionalidades](../guides/features/). +## 🛠️ Pila tecnológica + +- **Núcleo de la lógica**: [Kotlin Multiplatform (KMP)](https://kotlinlang.org/docs/multiplatform.html) +- **Runtime de Agente**: [Rust](https://www.rust-lang.org/) (Sidecars de alto rendimiento y CLI) +- **UI de Escritorio**: [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/) +- **Pila web**: [Astro](https://astro.build/), [Vue 3](https://vuejs.org/) y [Tailwind CSS](https://tailwindcss.com/docs) +- **Documentación**: [Starlight](https://starlight.astro.build/) +- **Sistema de construcción**: [Gradle](https://gradle.org/) y [Makefile](https://www.gnu.org/software/make/) + +## 📂 Estructura del Proyecto + +Este repositorio está organizado como un monorepo: + +```text +corvus/ +├── clients/ +│ ├── agent-runtime/ # Núcleo del Agente en Rust de alto rendimiento y CLI +│ ├── composeApp/ # Lógica de UI compartida para Escritorio/Móvil +│ ├── web/ # Monorepo Web (Docs, Dashboard, Marketing) +│ ├── androidApp/ # Wrapper específico para Android +│ └── iosApp/ # Wrapper específico para iOS +├── modules/ +│ └── agent-core-kmp/ # Lógica core en Kotlin Multiplatform y contratos +├── dev/ # Entorno de desarrollo local (Docker/Sandbox) +├── gradle/ # Lógica de construcción y configuraciones +└── Makefile # Punto de entrada estándar para tareas de desarrollo +``` ## Siguientes Pasos -Profundiza en: +¿Listo para empezar? -- [Configuración y Personalización](../guides/configuration/) -- [Flujo de Trabajo de Desarrollo](../guides/development/) -- [Proceso de Lanzamiento](../guides/release/) \ No newline at end of file +- **[Primeros Pasos](../guides/getting-started/)**: Instala y ejecuta tu primer agente. +- **[Referencia de la CLI](../guides/cli-reference/)**: Domina la interfaz de línea de comandos. +- **[Arquitectura](../guides/architecture/)**: Comprende el diseño del sistema. \ No newline at end of file