La Retama · digitalAIventures

Claudia Calvares — Agent Guide

Complete workflow: infrastructure, identity, capabilities, roadmap, and future enhancements for the La Retama AI shop manager.

5
Sessions done
17h 21m
Time invested
v0.16.0
Hermes Agent
€136.60
Billed so far

Contents

  1. System Architecture
  2. Session History
  3. Layer 1 — Infrastructure
  4. Layer 2 — Agent Core
  5. Layer 3 — Identity & Persona
  6. Layer 4 — Integrations
  7. Layer 5 — Owner Experience
  8. Roadmap — What's Next
  9. Suggested Enhancements
  10. Ops & Maintenance Reference
Done
Pending / In progress
Planned future
Suggested (new idea)
🏗️

System Architecture

Hardware

  • Lenovo laptop — Ubuntu 24.04 server
  • Lid-closed operation (AC power)
  • On-site at La Retama shop
  • Wi-Fi auto-reconnect configured

Remote Access

  • Tailscale — dedicated client tailnet
  • SSH key-only, UFW tailnet-bound
  • Portainer (Docker management)
  • Fail2ban, auto-updates

Agent Stack

  • Hermes Agent v0.16.0
  • Python 3.11 venv, unprivileged "hermes" user
  • Docker sandbox terminal backend
  • systemd user service (boot persistent)

AI Models

  • Primary: economical free-tier model
  • Delegate: stronger paid model (owner key)
  • TTS: Gemini voice (warm voice selected)
  • STT: on-device speech-to-text

Tools Enabled

  • DuckDuckGo web search
  • Gemini TTS (voice output)
  • Docker sandbox (code execution)
  • Read-only Odoo/ERP connector (built, parked)

Security Posture

  • Lynis hardening index: 76
  • No docker.sock, read-only mounts
  • Manual approval policy (fail-closed)
  • Env file mode 600, no key forwarding
Gateway pattern Claudia only knows users who have written to her in the current run — her contact directory rebuilds on restart. Proactive outbound messages to the owner must be triggered via the Telegram Bot API directly (not via the agent's own list). This is documented and worked around.
📋

Session History

Task 1 overall progress~45% complete
S1
Session 1 — Server Build
10 Jun 2026 · on-site · 5h 20m · €46.33
BIOS config, Ubuntu 24.04 install, SSH key chain, security hardening (UFW/fail2ban/auto-updates), lid/sleep immunity, Wi-Fi resilience, Docker + Portainer. Server delivered: hardened, sleep/reboot/Wi-Fi-resilient, remotely administrable.
S2
Session 2 — Security Audit + Agent Install
11 Jun 2026 · remote · 3h 05m · €24.67
Lynis audit (index 69→76), dead-man heartbeat monitor (healthchecks.io + Telegram alerts + email fallback), @laretama_manager_bot created, Hermes installed under unprivileged "hermes" user, Gemini TTS + DuckDuckGo tools configured, Telegram single-user allowlist, full unattended reboot test PASSED.
S3
Session 3 — Identity + Capability Tests
12 Jun 2026 · remote · 1h 30m · €12.00
SOUL.md written: "Claudia Calvares", shop manager persona with scope, hard boundaries, escalation rules, language policy (Spanish-first), shop facts. Supplier research test: 8 web searches, 3 distributors found, propose-then-confirm behaviour verified. Shop audio unlocked (PipeWire fix). Welcome serenade generated and cron-scheduled. Gemini free-tier rate limits identified as bottleneck.
S4
Session 4 — Credentials + Persona + Voice
13–14 Jun 2026 · remote · 4h 12m · €33.60
Zero-knowledge SETUP key intake (owner pastes key → auto-deleted from chat → stored in env 600). Two-model architecture finalised (economical primary + paid delegate). Owner Telegram ID added to allowlist. Safety boundary re-tests PASSED on new model. Andalusian portrait avatar generated on Replicate. Voice round-trip verified: owner voice note → STT → in-character spoken reply. PASSED.
S5
Session 5 — Incident Triage + Owner Channel + ERP Prep
15 Jun 2026 · remote · 2h 44m · €21.86
Internet outage incident diagnosed (server fine, dead-man worked). Owner proactive messaging fixed (API path confirmed). Developer auto-notification rule added (summary on owner message). Capability-honesty safeguard added (no overstating unbuilt features). Invalid delegate key discovered — re-supply deferred to setup day. Read-only Odoo stock connector built and parked. Email assessed: draft-only design agreed.
S6
Session 6 — Owner Setup Day
~2 weeks out · ~3h estimated · pending owner availability
Owner supplies valid paid AI key → delegate activated. Owner self-serves ERP staging copy + read-only API key → stock connector activated. Signed-email draft test. Owner home channel first guided chat. Remove one-shot serenade cron.
🖥️

Layer 1 — Infrastructure

Sessions 1–2
✓
Ubuntu 24.04 server install
BIOS AC-restore, lid-close immunity via systemd+GNOME+GDM, Wi-Fi auto-reconnect, battery conservation. Zero on-site visits required after delivery.
DONE
✓
Tailscale + SSH hardening
Dedicated client tailnet, SSH key-only auth, UFW tailnet-only policy, fail2ban (with self-ban fix), unattended upgrades.
DONE
✓
Docker + Portainer
Docker daemon hardened, Portainer on tailnet-bound port. Docker sandbox backend used by Hermes for safe code execution (no docker.sock, read-only mounts).
DONE
✓
Lynis security hardening
Full Lynis audit cycle: index 69→76. SSH batch hardening, unused kernel protocols blacklisted, sysctl hardening applied. Zero warnings.
DONE
✓
Dead-man heartbeat monitor
healthchecks.io (5 min period / 10 min grace), server heartbeat cron, Telegram "DAV Infra Alerts" group + email fallback. Validated in real incident (S5): short internet outage correctly diagnosed as non-server event.
DONE
✓
Shop audio (PipeWire)
Triple PipeWire instance issue diagnosed (login screen held sound card). Agent user granted audio device access. Microphone + speakers confirmed available to agent.
DONE
+
Lynis re-audit to push index above 80
One more hardening pass targeting remaining quick wins (AppArmor profiles, auditd, PAM hardening). Goal: Lynis ≥80 as a milestone for "production-ready" sign-off.
IDEA
+
Automated nightly backup snapshot
Rsync or borgbackup cron to a remote target (e.g. Backblaze B2 or another Tailscale node). Backs up SOUL.md, env file, Hermes config, logs. Recovery time from scratch: currently ~2h; backup reduces it to ~15m.
IDEA
🤖

Layer 2 — Agent Core

Sessions 2–4
✓
Hermes v0.16.0 install
Installed under unprivileged "hermes" user (no sudo, no vault access). Python 3.11 venv, hash-verified. Optional browser engine deliberately skipped. PATH wired. systemd user service with lingering → boot persistent.
DONE
✓
Two-model architecture
Primary: economical free-tier (stable, no throttling). Delegate: stronger paid model, funded via owner's own key through zero-knowledge intake. Top-tier unavailable (export controls June 2026).
DONE
✓
Tool set configured
DuckDuckGo web search (live, tested), Gemini TTS voice output (warm voice selected by owner), Docker sandbox terminal execution, STT (on-device). Browser and image-gen deliberately disabled.
DONE
✓
Safety sandbox verified
Manual approval policy (fail-closed), no cron auto-approval. No docker.sock, read-only mounts, no env forwarding into sandbox. Secret-disclosure and destructive-command refusals verified on live model.
DONE
✓
Zero-knowledge credential intake
Owner sends SETUP <KEY> <value> via Telegram. Intercepted before AI processes it, written to env file (mode 600), source message auto-deleted, confirmation replied. Developer never sees the key. Installed as a proper Hermes plugin.
DONE
✓
Capability-honesty safeguard
Explicit rule added: Claudia must state clearly what integrations are NOT yet active rather than implying they work. Triggered after she overstated stock-reading ability to the owner (S5). Correction was issued.
DONE
!
Delegate AI key — activate stronger model
The key on file from S4 was invalid (mistyped entry). Owner must re-supply a valid key via SETUP command at the setup day. Until then, only the primary model is active.
PENDING
+
Model auto-router (smart delegate)
Add a routing rule so Claudia automatically escalates to the delegate model for: complex multi-step tasks, legal/supplier negotiations, anything with financial impact. Falls back to primary for simple Q&A and routine lookups. Saves owner's delegate quota.
IDEA
+
Persistent memory / context across restarts
Currently the contact directory resets on restart. Consider a lightweight SQLite log of: (a) recent conversation summaries, (b) known contacts, (c) pending tasks. Claudia reads this on boot and "remembers" she was talking to the owner. Hermes has a memory plugin — check if it supports custom storage backends.
IDEA
+
Daily usage digest to developer
Nightly cron: Claudia summarises the day's conversations (topic categories, owner query count, tool calls made, errors) and sends a brief report to the developer Telegram. Early warning for misuse, bugs, or capability gaps without reading every message.
IDEA
🎭

Layer 3 — Identity & Persona

Sessions 3–4
Current persona "Claudia Calvares" — general business manager for La Retama. Spanish-first (mirrors sender language). Warm-professional tone, respectful Andalusian cultural warmth. Warm portrait avatar set. Voice: owner-preferred warm Gemini neural voice.
✓
SOUL.md — full identity document
Scope of duties: stock/Odoo, suppliers, sales advice, email, customer service. Hard boundaries: propose-then-confirm for payments/prices/orders, no secrets disclosure, no destructive commands, no real third-party contact in testing. Escalation rules: technical → developer, business → owner.
Language policy: Spanish first, mirror sender
Shop facts: opening hours, location, product categories, values (ecobio/local)
Testing-mode awareness: knows it's in testing, behaves accordingly
DONE
✓
Avatar — Andalusian portrait
Generated via Replicate (multiple prompt/image iterations), warm and culturally appropriate. Set as @laretama_manager_bot Telegram avatar.
DONE
✓
Voice round-trip verified
Owner sends voice note → on-device STT → Claudia processes → Gemini TTS warm voice → reply as voice note. Full voice conversation flow confirmed working end-to-end.
DONE
+
Seasonal + event-aware personality layer
Add a lightweight calendar awareness: Claudia knows current month/season and adapts greetings. Ramadan greetings for Yacub, local Spanish fiestas awareness, harvest season context for ecobio products. Adds warmth with minimal complexity.
IDEA
+
Arabic language support
The S3 serenade included an Arabic greeting. Claudia's language policy should explicitly include Arabic as a supported language for owner communications (Yacub is likely Arabic-speaking). Test that the TTS voice handles Arabic well or select an appropriate Arabic voice option.
IDEA
+
Shop opening hours automation
SOUL.md knows the hours. Add a rule: if a customer (future: multi-user) asks "are you open?", Claudia checks the current time and answers factually. Can also trigger a "shop opens in X hours" audio announcement via the shop speakers via cron.
IDEA
🔌

Layer 4 — Integrations

Sessions 5–6+
✓
DuckDuckGo web search
Live and tested. Supplier research scenario passed: 8 searches, 3 relevant Andalucían organic distributors returned with shop-fit reasoning. No real contact attempted (testing mode).
DONE
✓
Read-only Odoo stock connector (built, parked)
Structurally read-only — can query product and stock data, never modify. Built in S5, syntax-validated, dormant until staging credentials are added. Safe to ship now.
DONE
!
Odoo staging credentials + connector activation
Owner must self-serve a staging Odoo copy and generate a read-only API key. Developer activates the parked connector with staging creds. First tests: product lookup by name, stock level query, low-stock alert. Blocked on owner setup day.
PENDING S6
!
Email — draft-only integration
Design agreed: Claudia drafts emails, owner reviews and sends. Email currently unwired (safe by default). Needs: SMTP credentials (owner-supplied), draft-email plugin installed in Hermes, proposed template tested (supplier enquiry). Pending S6.
PENDING S6
→
Odoo write access (price edits, stock adjustments)
After read-only is stable and trusted: expand connector to allow Claudia to propose price changes or stock adjustments via the propose-then-confirm flow. Owner confirms in Telegram → Claudia writes to Odoo. Requires separate approval gate in SOUL.md.
FUTURE
→
Supplier contact (email send)
After draft-only email is proven: add a send capability gated behind explicit owner confirmation per message. Claudia drafts → owner says "send it" → email dispatched. Confirm real third-party contact rules in SOUL.md updated before activating.
FUTURE
+
WhatsApp Business integration
Many Andalucían suppliers and customers use WhatsApp. Hermes supports multiple gateways. A WhatsApp Business channel (Twilio or Meta Cloud API) would let Claudia handle customer enquiries at scale. Pilot: customer-facing FAQ bot, then supplier communication.
IDEA
+
Low-stock proactive alert
Once Odoo connector is live: add a cron that checks stock levels each morning and sends Yacub a Telegram message listing products below reorder threshold. Claudia frames it as "Good morning, here's what needs ordering today:" with suggested quantities.
IDEA
+
Price-comparison web research
Extend the existing DuckDuckGo tool: Claudia can research competitor prices for key products (e.g. aceite ecológico, miel de la Alpujarra) and report them to the owner weekly. Uses existing search capability, just needs a scheduled trigger and a report format.
IDEA
+
Shop camera / door sensor input
If the shop has or gets a camera or door sensor: pipe a simple motion/open event into Hermes. Claudia could log shop open/close times, alert Yacub if the shop is still open past closing time, or trigger a welcome announcement when someone enters.
IDEA
👤

Layer 5 — Owner Experience

Sessions 4–6
✓
Owner Telegram onboarding
Owner Telegram ID recovered from gateway rejection logs, added to chat allowlist and SETUP key intake authorized list. Two-way channel confirmed working.
DONE
✓
Developer auto-notification
Standing rule: whenever the owner writes, Claudia alerts the developer with a short summary. Verified firing live on real owner messages. Allows developer to monitor without reading every conversation.
DONE
✓
Welcome voice greeting delivered
Spanish + Arabic greeting TTS generated, delivered via Telegram. Owner replied and engaged. One-shot serenade cron still active — remove at S6.
DONE
!
Remove one-shot serenade cron
The welcome cron is a one-shot that fires at 20:30. Confirm it has fired, then remove to keep the crontab clean.
PENDING S6
!
Owner home channel + first guided chat session
Dedicated session where Yacub gets hands-on time with Claudia guided by the developer. Cover: how to ask for stock info, how to trigger a supplier email draft, voice message flow, what to do if something breaks.
PENDING S6
→
Owner runbook (self-service guide)
A simple PDF or Telegram-pinned message the owner can reference: how to supply a new key, how to restart the agent if needed (via Portainer), what the dead-man alerts mean, who to contact. Reduces developer call-outs.
FUTURE
+
Shop morning briefing
Each morning at a configured time (e.g. 8:30), Claudia sends Yacub a voice or text message: today's date, any low-stock alerts from Odoo, any pending supplier replies, any scheduled deliveries (if calendar integration added). Makes Claudia feel like a real business manager starting the day.
IDEA
+
Multi-user allowlist (staff / family)
Hermes supports a user allowlist. Add a family member or shop assistant as a secondary user with a more restricted role (e.g. can query stock, cannot modify anything). Claudia already knows to escalate business decisions to the owner.
IDEA
🗺️

Roadmap — What's Next

Gate condition Strongly advised: keep read-only / staging / draft-only testing phase before any live-shop hook-up. No live Odoo writes, no real email sends until staging is proven stable for at least 2 weeks.
1
Session 6 — Owner Setup Day
Blockers on owner: valid paid AI key (SETUP command), Odoo staging copy + read-only API key.
Owner supplies valid delegate key → activate stronger model
Odoo staging creds → activate read-only stock connector
Test: "Claudia, how many kilos of garbanzos do we have?"
Draft email test: "Claudia, write to Distribuidor X asking for prices"
Owner guided chat session (first real use)
Remove one-shot serenade cron
NEXT
2
Phase: Read-Only Stable (2–4 weeks after S6)
Monitor real usage. Validate that stock queries work reliably, email drafts are useful, no false capability claims. Fix any bugs. Gather owner feedback on what else Claudia should know or do.
FUTURE
3
Phase: Write Access + Email Send
After stable: Odoo write access (propose-then-confirm flow for price edits, stock adjustments). Email send capability (per-message owner confirmation). Possibly WhatsApp gateway for supplier reach.
FUTURE
4
Phase: Autonomous Shop Manager
After write access proven: add daily briefings, low-stock auto-alerts, price comparison research, supplier shortlist maintenance. Claudia becomes a genuine daily co-manager rather than an on-demand assistant.
FUTURE
💡

Suggested Enhancements — Full Hermes Capabilities

What Hermes can do that we haven't used yet These are capabilities native to Hermes that are not yet wired for Claudia. Each would make her meaningfully smarter or more autonomous.
+
File ingestion — supplier pricelists, invoices
Hermes can accept file uploads via Telegram. Yacub could forward a supplier PDF pricelist → Claudia reads it, extracts product/price table, compares to current Odoo prices, flags discrepancies. Huge time saver for a shop with many suppliers.
HIGH VALUE
+
Photo-to-product lookup
Hermes supports image input. Yacub photographs a product label → Claudia identifies it (web search + image analysis) and tells him: current stock level in Odoo, supplier, last purchase price. Useful at the market, in the stockroom, or when a customer asks about something.
HIGH VALUE
+
Structured task / to-do tracking
Claudia maintains a lightweight task list in a local JSON file (or simple Odoo note). Yacub says "remind me to call Distribuidor X on Friday" → Claudia adds it, sends a Telegram reminder at the right time. Uses Hermes scheduling + local state.
IDEA
+
Sales reporting from Odoo
Once Odoo connector is live: weekly sales summary (top products, revenue, slow movers). Claudia sends it every Monday morning as a voice note or Telegram message. Uses existing read-only access — no new permissions needed.
IDEA
+
Competitor / market monitoring
Weekly cron: Claudia searches for prices of La Retama's top 10 products at competing local shops (web search). Sends Yacub a "market pulse" summary. Helps pricing decisions without Yacub needing to do the legwork.
IDEA
+
Shop ambient announcement (TTS to speakers)
Audio is already wired. Claudia can play announcements through the shop speakers on demand or on a schedule. E.g. "Buenos días, bienvenidos a La Retama, hoy tenemos aceite nuevo de la cosecha 2025..." Triggered by Yacub's Telegram command or automatically at opening time.
IDEA
+
Hermes plugin: custom reorder calculator
A small Hermes plugin that: pulls current stock from Odoo, applies a simple reorder formula (days of stock remaining = stock / avg_daily_sales), and outputs a prioritised "order now" list. Claudia presents this to Yacub with suggested quantities. Requires 30–60 days of Odoo sales history.
IDEA
⚙️

Ops & Maintenance Reference

Remote access

  • SSH via Tailscale (key auth only)
  • Portainer on tailnet port
  • No direct internet SSH exposure
  • Android → Termux/JuiceSSH

Agent service

  • systemd user service, lingering
  • Restarts automatically on crash
  • Contact dir rebuilds on restart
  • Check: journalctl --user -u hermes

Monitoring

  • healthchecks.io dead-man (5/10 min)
  • Telegram "DAV Infra Alerts" group
  • Email fallback alert
  • Brief internet outage = expected (self-recovers)

Key management

  • All keys in KeePassDX
  • Agent env file: mode 600
  • Owner keys: SETUP command (never seen by dev)
  • Bot token: KeePassDX entry
Internet outage protocol If "server down" alert fires: (1) wait 15 minutes — most outages are brief shop internet blips and the server self-recovers. (2) If alert persists: SSH in via Tailscale, check systemctl --user status hermes. (3) If SSH unreachable: physical visit or ask Yacub to reboot the laptop. The dead-man has a 10-min grace so short outages don't page.
Before any Odoo write access goes live Full staging + read-only phase required (minimum 2 weeks). Update SOUL.md approval gates. Test propose-then-confirm flow on staging Odoo before touching production. Get explicit owner sign-off.
# Useful quick commands (via Tailscale SSH) systemctl --user status hermes # Agent status journalctl --user -u hermes -f # Live logs systemctl --user restart hermes # Restart agent crontab -l # Check crons (remove serenade after S6) cat ~/.config/hermes/env # Verify key stored (do NOT print value) lynis audit system # Re-run security audit