Carl AI
Carl is an independent agent application built on the KofTwentyTwo Agent Foundation. Its first-release financial mission is to reduce debt and make sustainable cash-flow plans, then improve rental/tax structure and plan investment against agreed milestones. Carl owns its domain records, services, reasoning and QQQ administration. External financial/vendor actions remain human-led; the designated shared Synology calendar/reminder workspace has separately authorized maintenance scope.
Current state (2026-10-02): source commit 9bd782e passes 566 tests against foundation main d0a11bf. The owner's local runtime still runs the older 563-test package; it is local only, and no preview URL is live. Owner chat currently fails (Carl#34); fixes are in local branches pending push. See current state; other counts in these docs are historical.
Whole-product acceptance remains incomplete. The working application uses real data and verified identity: the owner authorizes the supplied real Monarch exports as private local data, kept out of this repository, commits, CI artifacts and diagnostics. Synthetic records are controlled regression fixtures only. Authentik and calendar/reminder integration are deferred by the owner. Missing account, debt, cash and rental facts keep financial coverage PARTIAL. Liquibase and hosted CI/CD qualification continue. Carl development uses foundation 0.5.0-SNAPSHOT with exact QQQ 4.1 development artifacts and Next UI 1.0.0-RC.8; adopting the published QQQ 4.1.0-RC.1 and a newer frontend is separately unqualified.
Read the requirements, financial planning scope, Monarch workflow, decisions, current session state and acceptance. See the real-data readiness limits and native action map before QA. Track application work in Carl issues; reusable infrastructure belongs in the foundation tracker. GitHub Projects are not required.
Build and local verification
Use Java 21, Maven 3.9+ and Docker for disposable PostgreSQL tests. Run mvn spotless:apply verify; the distribution is target/agent. Open this directory as a Maven project in IntelliJ, select Java 21 for the project and Maven runner, and run the same verify lifecycle. AgentApplication.main and tests use the same component factory.
The current parent is com.kof22:kof22-agent-parent:0.5.0-SNAPSHOT, now independently published and qualified from foundation main d0a11bf/run36974782652. The development CI pin records all nine identities in config/ci/foundation.json; matching consumer qualification is separate. Carl’s current frozen package was built with separately qualified local development artifacts; use -Dmaven.repo.local for that exact cache. Fresh Carl remote resolution still requires authorized private package credentials. The remote release baseline in config/release/foundation.json deliberately remains0.4.1: RC/stable promotion will refuse this development parent until its matching foundation release is published and independently qualified. A clean public-consumer checkout still needs private Maven package access for published artifacts. The final consumer build is verified separately from upstream publication. The consumer repository token alone is not assumed to grant cross-repository package access. Supply secrets privately through the environment and use --settings config/maven/settings.xml.example; do not store a token in this repository.
The following browser fixtures are controlled regression tooling only. Never offer fixture sign-in, fictional records or scripted providers as the working Carl UI. Run packaged browser checks with npm ci --prefix scripts/e2e, npx --prefix scripts/e2e playwright install chromium, then bash scripts/verify-browser.sh after the Maven build. The fixture uses synthetic PostgreSQL records and local TLS/OIDC; ordinary checks use a disconnected model. Set CARL_QUALIFIED_DISTRIBUTION to the reviewed distribution and run scripts/verify-dashboard-browser.sh and scripts/verify-talk-browser.sh for the native process UI checks; run scripts/verify-docked-chat-browser.sh for the dock; scripts/verify-qbits-browser.sh checks actual OpenSearch and Artemis integration. Live synthetic preview inference is separately opt-in and requires the already-authorized credential through the foundation runtime variable KOF22_AGENT_ANTHROPIC_API_KEY (the unprefixed legacy name is not read by the harness); never paste it into source or configuration. Optional MAVEN_SETTINGS and MAVEN_REPO select an isolated qualified development cache.
Run the representative model evaluation against the frozen reviewed package. Controlled tooling is qualified; real model cases require an explicitly selected model and privately supplied authorized credential.
See operator instructions, family API integration, and acceptance evidence. Do not connect personal sources or expose this development application publicly until the outstanding acceptance and deployment work is qualified.
The owner’s build-journal blog drafts are kept in the owner’s private notes, outside this repository.