Chapters

DOC-05 / Technical reference · Chapter 10

Catalogue of Synedre OS Facades & Entrypoints

Inventories and describes all executable entry points of the agentic harness (synedre/*.py and bin/*) with their family, role, and invocation mode, enabling an engineer to quickly navigate the repository.

Catalogue of Facades & Entry Points — Synedre OS

This chapter lists the executable entry points of the Synedre OS agentic harness. For each one, it indicates its family, its role in a single line, and its typical invocation mode, so that an engineer picking up the project can quickly identify which component does what without having to browse the entire source code.

Scope, Method and Coverage

Extraction Method

The descriptions presented here are extracted programmatically from the first docstring or leading comment of each source file. They were not invented. When a file carries only a copyright header as its docstring, the actual role was read from the next descriptive line. This fallback is not systematic: it applies only to files whose real docstring is displaced by an author banner. The role remains accurate, but the extraction cannot be described as uniformly positioned at a fixed line.

Coverage Count

Category Actual Total Covered in This Catalogue
Main harness scripts 261 Main scripts detailed by family below; certain one-off utilities or one-shot tests listed in §0 only
bin/ entries (including subdirectories) 83 entries Executable scripts detailed below; SQL/JSON migration files, configuration files, and compiled cache not detailed individually

The bin/ directory breaks down into 81 top-level files (Python, Shell, JavaScript, JSON, SQL scripts, and one extension-less script) along with two subdirectories: an SQL migrations folder (12 files) and a compiled cache. A library subdirectory for the Active-Record entity layer additionally exposes two CLI facades documented in the dedicated entities section.

Recently added components include notably: a product scraping module, a pre-production injection tool, a brand consistency auditor, an error reflex manager (session stop hook), a per-client tone detector (prompt submission hook), as well as several modules related to organ flows, agentic immunity, SEO coverage, deliberation, PDF signing, module installation, and content synchronisation.

Crontab verified: cross-referencing active scheduled tasks against scripts present in the repository confirms zero dead cron entries in uncommented lines. Previously scheduled scripts were removed during a migration of the automation directory tree. No residual cleanup is required.

Invocation Mode Legend

Code Meaning
cron Launched by the task scheduler, often via the centralised cron watchdog
CLI Invoked manually from the terminal
skill Facade behind a skill declared in the agent skills configuration
hook Agent hook triggered on a session event (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop)
lib Imported module, not a standalone entry point
worker Daemon or loop draining a database queue

Families & Overall Flows

                  ┌────────────────────────────────────────┐
 inbound email ──►│  Email reception & synchronisation     │
                  └──────────────────┬─────────────────────┘
                                     │ intent classification
                                     ▼
                  ┌────────────────────────────────────────┐
 /hub, CLI   ───► │  Orchestration (spawn, react, QA)      │
                  └──────────┬────────────────┬────────────┘
                             │                │
                 worksites   │                │  brainstorm
                             │                │
                             ▼                ▼
      ┌──────────────────────────────────────────────────┐
      │       Agent execution (agent call, reaction)     │
      └──────┬───────────────────────────────────────────┘
             │
  ┌──────────┼───────────┬─────────────┬────────────────┐
  ▼          ▼           ▼             ▼                ▼
audits    blog/SEO    finance      browser         deployment
  │          │           │             │                │
  └──────────┴───────────┴─────────────┴────────────────┘
                         │
                         ▼
              PostgreSQL database
              Unified access via the persistence facade
              and the centralised environment loader

Data model — key points: all facades access the database through a single Python abstraction layer and a centralised environment variable loading module. Secrets (passwords, API keys, tokens) reside exclusively in environment files ignored by the version control system — never in plaintext in the code.

Common Foundation — Cross-Cutting Libraries & Facades

Component Role Invocation
PostgreSQL persistence facade Unified Python database access layer for all automations lib
Connection helper (sandbox) Lightweight database connection for agents running in sandbox mode lib
Environment loader Centralised loading of all environment variables lib
Structured logging Mandatory, uniform logging for all automations lib
Cron watchdog Autonomous monitor for the execution of scheduled automations cron (wrapper)
Agnostic AI facade Multi-provider AI abstraction (Mistral, Claude, OpenAI, vector embeddings) lib
Agent invoker Allows any automation to trigger a Synedre agent CLI / lib
Persona loader Loads an agent's cognitive profile and persona from the agent registry lib
Embedding facade Computation and management of product embedding vectors (search optimisation) lib
Event persister Records a JSON event stream into the agent traceability table lib
Personal data filter Strips personally identifiable data before submission to the LLM pipeline lib
Reflex engine Decentralised control facade: reads the incoming hook event, loads active reflex rules, returns a deny / warn / allow decision, and records the outcome to the database. Extended to cover read-tool, agent-call, and web-browsing tool families. Asymmetry principle: every new reflex tightens policy — sensitive areas are closed by default (fail-closed) hook (PreToolUse — edit, write, read, agent call, browsing)
Base reflex initialiser Idempotent seed of foundation-level reflexes into the reflex registry — descriptive only, not evaluated at runtime; the source of truth for hook wiring remains the hook configuration CLI (migration/init)
Extended reflex initialiser Idempotent seed of reflexes covering read operations, agent calls, and web browsing — purges then reinserts; protection against dangerous regular expressions via alarm timeout; path patterns are pure substrings, not regexes CLI (migration/init)
Shell deployment library Utility functions shared across all deployment scripts lib
Deployment manifest parser Reads and validates the YAML deployment manifest, emits the corresponding shell key-value pairs lib

Orchestration family — the agentic core

This family groups all components that drive the agent lifecycle: incoming request intake, intent classification, language model invocation, execution tracking, and automatic recovery from stalled states.

Invocation doctrine: every programmatic call to an agent must go through the spawn engine via pseudo-terminal (node-pty). Direct command-line invocation is prohibited. The spawn component enforces this constraint across the entire system.

Core components

Component Role Invocation mode
Incoming message collector Polls the Atlas agent inbox every 5 minutes Scheduled task
Intent classifier Labels each incoming message: run, project, question, or noise — via a language model Library / CLI
Classifier calibrator Monthly recalibration of the intent classifier Scheduled task
Spawn engine Tier 2: instantiates the agent in headless mode to process classified messages. 40-minute timeout (progressively extended from 10 min). Includes an anti-concurrency mechanism: if the result event is lost during output buffer flush, the system re-reads the stream log to prevent false negatives. Maximum 3 simultaneous instances per cycle. Worker
Attachment extractor Extracts and antivirus-scans files attached to incoming messages Library
Reply sender Sends responses by email with triple anti-spoofing verification CLI
Post-send monitor Monitors delivery after dispatch and triggers an automatic rollback (once at most) Scheduled task
Consolidated health report Produces an overall health summary of the agentic system CLI
Per-task reflex engine Runs the Observe–Reflect–Act (ReAct) cycle for each task, following the chantier-v2 doctrine Worker
ReAct pattern recorder Automatically records recurring patterns produced by ReAct cycles Scheduled task
Task worker Main task execution daemon (cockpit dashboard) Worker
Assisted unblocking Atlas drafts an unblocking plan for a stalled task CLI
Automatic stall detector Detects stalled tasks and automatically instantiates Atlas to unblock them Scheduled task
Runaway detector Automatically pauses tasks that have been blocked for more than 3 hours or have exceeded 150,000 tokens consumed Scheduled task
Question interface Console chat session dedicated to questions addressed to Atlas CLI
Run interface Console chat session scoped to a specific run CLI
Formalisation worker Hosts the mission statement formalisation process Worker
Daily ReAct summary Generates a consolidated summary of ReAct cycles every day at 03:30 UTC Scheduled task
Daily summary prompt Contains the prompt and few-shot examples for the daily summary Library
Local HTTP daemon HTTP daemon accessible locally only, serving internal command execution Worker
node-pty spawner Instantiates the agent via pseudo-terminal and streams standard output. Flushes the buffer before terminating the process to prevent stream truncation (fix applied after the last line was lost during a partial flush, producing spurious empty results). SIGKILL timeout properly wired before the exit callback. Library
Atlas post-deployment QA Two-level quality control after each Atlas deployment Scheduled task / CLI
Spawn dashboard Real-time CLI display of Atlas spawn activity CLI
tmux wrapper tmux wrapper for agent control via the hub CLI
Spontaneous patch worker Detached worker that instantiates a correction agent as soon as a bug is detected Worker
Nightly loop trigger Initialises autonomous-mode projects every hour (19:00–05:00 UTC window): seeds a pending task for the next eligible run, subject to a cost ceiling and a circuit breaker. Simulation mode is active by default. Scheduled task
Image OCR extractor Extracts text from images attached to messages via local OCR (Tesseract). Includes prompt-injection protection, limited to 3 images of 5 MB each. Library
Lock watchdog Raises an alert if the message collector lock remains present for more than 10 minutes (zombie lock) Scheduled task (every 15 min)
OCR dependency installer Installs the Tesseract dependencies required for OCR extraction — to be run once only CLI (one-shot)

Sub-family: interactive session → cockpit bridge

Pipeline added to allow an interactive agent session to declare the project it is driving and feed the dashboard in real time. A global circuit breaker allows this bridge to be disabled without disrupting the rest of the system. When no active binding is present, the bridge is fully transparent. The node-pty spawner remains the sole authorised component for headless invocations.

Component Role Invocation mode
Binding manager (part 1/3) Declares or revokes the association between an interactive session and a project, via a temporary state file Library / CLI
Event hook (part 2/3) Invoked after each tool use by the agent; reads the JSON input, synthesises a stream event, and pushes it into the agent event log if a binding is active Library (hook)
Lifecycle manager (part 3/3) Activates and deactivates cockpit surfaces according to execution state: pulses "in progress" on the run, updates doing/done cards on project tasks, polled every 5 seconds Library
Cockpit message emitter Emits on demand a message or reflection fragment into the cockpit timeline, under the active binding's persona CLI / Library
Cockpit negotiation log Emits structured events (note, strategy, decision, objection, next step…) into the negotiation log, targeting the commercial cockpit timeline — raw tool calls (shell noise) are never emitted CLI / Library
Bridge diagnostic Checks the state of the binding, hooks, and circuit breaker, and displays the last emitted event — read-only, no side effects CLI
Bridge smoke test Validates event synthesis and anti-leak masking on an isolated temporary binding, in pure Python with no database writes CLI (test)

Sub-family: multi-LLM agentic execution

Provider-agnostic execution architecture: a common interface contract (AgentRunner) is implemented by N backends, selected per job via the routing field associated with each job. All events feed the agent event log (cockpit); costs are tracked in the financial tracking tables by reference to a pricing catalogue — no price is hard-coded. Available backends: pseudo-terminal invocation (existing, unchanged) and a custom agentic loop over a direct API (OpenAI-compatible format). Planned backends: direct API SDK for the primary provider, adapters for other providers.

Component Role Invocation mode
AgentRunner contract + pseudo-terminal backend Defines the common interface and implements the pseudo-terminal invocation backend (node-pty spawner) without modifying the existing task worker. Exposes backend resolution and cost registration functions. Library
Multi-LLM FinOps foundation Computes cost per (provider, model) pair from the pricing catalogue, aggregates by project, and breaks down by provider. CLI interface: pricing display, run cost, per-project breakdown. Library / CLI
Backend router Reads the job routing field and dispatches to the named backend. On resolution failure, falls back to the pseudo-terminal backend by default. Library / CLI
Custom loop backend Implements the provider-agnostic custom agentic loop: calls the LLM API directly (Mistral as first backend, OpenAI-compatible format), reuses common result and event structures, and registers costs via the FinOps foundation. Library
Premium replay cron Probes the primary provider's quota. If the quota is available again, replays high-priority tasks that were previously routed to a fallback provider during a cap event. Does nothing if the quota is exhausted or there is nothing to replay. Scheduled task

Project family — seven-step workflow

This family manages the full lifecycle of a project: from receipt of a client email through to delivery, including team assembly, task breakdown, budget tracking, and commercial qualification. The official creation entry point from an email is the project creation script from an incoming message, accessible via the dedicated skill.

Component Role Invocation mode
Project creation from email Creates a client project from an incoming message (steps 0a to 4, subject to validation constraints) CLI / skill
Live monitoring Displays agent events on an active project in real time CLI
Mission statement generator Produces a draft mission statement for a project Library
Team management Manages the teams recruited for each project Library
Session manager Active Record for agent sessions associated with projects Library
Discovery breakdown pipeline Automatically decomposes a discovery phase into implementation tasks via LLM Worker
Post-breakdown audit Atlas audits the result of the discovery breakdown CLI
Relevance audit Assesses the relevance of active projects Scheduled task
Acceptance QA Acceptance quality control on a specific project CLI (one-shot)
Negotiation job starter Launches the job associated with a commercial negotiation CLI
Negotiation event extractor Asynchronous worker that enriches unprocessed negotiation events Worker
Negotiation proposal backfill Retroactively repopulates the proposals table associated with negotiation events CLI (backfill)
Negotiation reclassifier Moves a miscategorised negotiation to the correct category CLI
Lead scanner Detects and qualifies incoming leads from Calendly bookings Scheduled task / skill
Job validation QA Validates a completed job by the team that executed it Worker
Token estimator Estimates token volume and recommends a suitable model for a given task Library
Token estimator prompt Contains the prompt and few-shot examples for the token estimator Library
Actual token feed Updates the counter of tokens actually consumed by each task from the JSONL log Scheduled task
Pattern detector Identifies recurring patterns in task iterations Scheduled task
Bug detector Detects pre-existing bugs in agent runs before execution Library
Run entity backfill Recreates missing run and question entities in the log CLI (backfill)
Project lock cleanup Purges expired project locks according to a TTL policy Scheduled task
Cascading resolution E2E tests End-to-end validation of the cascading dependency resolution mechanism CLI (test)
Parallelism E2E tests Validates concurrent multi-terminal access behaviour on project locks CLI (test)
Lock rollback SQL script to manually cancel a blocking project lock SQL
Budget alert Sends an alert email when a project reaches 80% of its cost ceiling — idempotent via state file. ⚠️ Not yet scheduled (present on disk, absent from the scheduler as of 07/06/2026 — invocable via CLI; target cadence: every 15 minutes). CLI / scheduled task (to be wired)
Company enrichment Legally qualifies and assesses the creditworthiness of a prospect via public registries (SIRENE, BODACC, Pappers optionally). Feeds the negotiation qualification profile and generates a synthesis deliverable. CLI / Library
Negotiation Active Record Provides the full context of a negotiation (client, contacts, events, linked project, qualification, deliverables) and initialises the folder tree with seven template deliverables (idempotent operation). CLI interface for read, initialisation, and listing. Facade for the negotiation skill. Library / CLI
Run Active Record Provides the full context of a run (resolved scope: mothership, tenant, or negotiation, along with associated task executions for reference purposes). CLI interface for read and listing. The run is the recommended default entry point. Note: a run (business scope unit) is distinct from a task execution by the agent (technical execution unit). Library / CLI

Brainstorm Family

This family groups the automations dedicated to generating, maturing and promoting ideas within the platform. Work items are handled through a dedicated queue. A continuously-looping daemon handles primary processing, while a scheduled safety net (single-execution mode) ensures no idea remains stuck in the event of daemon failure.

Component Role Invocation mode
Brainstorm queue worker Drains the brainstorm work queue and dispatches tasks Worker / scheduler (single execution)
Gestation conversation Phase-1 dialogue with the Atlas agent to surface an idea Command-line interface
Sequential challenge Submits an idea to successive critique by the high-orbit agents Worker
Narrative synthesis Generates the structured narrative summary of a mature idea Internal library
Promotion bridge Moves a validated idea from brainstorm to an active project (or marks it as abandoned); triggered by the /idee command Command-line interface / agent skill
Demotion bridge Mirror operation: moves a project back to the brainstorm phase Command-line interface

Audits, Quality and Security Family

This family groups all automations responsible for monitoring, inspecting and certifying platform health: infrastructure, database, dependencies, accessibility, SEO, security and visual quality. The vast majority of these components run on a scheduled basis (cron) or on demand via an agent skill.

Infrastructure and database audits

Component Role Invocation mode
Nightly automation auditor Reviews all platform automations every night (driven by the Renoir agent) Scheduler
Nightly multi-agent audit Collective inspection by multiple agents; no automatic correction — report only Scheduler
Database schema auditor Checks daily that the data schema conforms to official naming conventions Scheduler
Schema drift detector Detects discrepancies between TypeScript schema declarations and the actual state of the database Scheduler
Backup monitor Daily check of the presence and freshness of database backups hosted on object storage Scheduler
Monthly restore test Verifies each month that a stored database dump can actually be restored Scheduler
Local backup freshness checker Checks the integrity and freshness of local backups; also triggered by the /backup-verify skill Command-line interface / agent skill

Security and dependency audits

Component Role Invocation mode
Dependency audit Reviews known vulnerabilities in JavaScript and Python packages Scheduler
Penetration testing automation Runs an automated pentest driven by the Mitnick agent; triggered by the /security skill Command-line interface / agent skill
Unified infrastructure audit Inspects the mothership VPS and client VPS instances; triggered by the /infra skill Command-line interface / agent skill
Unified security audit Security analysis covering the mothership VPS and client VPS instances; triggered by the /security skill Command-line interface / agent skill
Schema/code consistency guard Pre-commit gate: rejects any column referenced in raw SQL but absent from the declarative schema from passing to commit; multi-application scope, analyses staged files only Control gate (pre-commit)
Open-source readiness scanner Inspects the source code of public directories to detect any reference to internal identifiers or client names before publication Command-line interface

Quality and accessibility audits

Component Role Invocation mode
Accessibility audit Checks WCAG 2.2 Level AA compliance of public pages (Braille agent) Command-line interface
Blog article audit Multi-agent analysis of the editorial and technical quality of an article Command-line interface
Public page quality audit Inspects page quality and applies targeted automatic corrections Command-line interface
Agent data audit Verifies the consistency of agent configuration data via the API Command-line interface
Component checker Validates the integration checklist of a UI component before production release Command-line interface
Anti-hallucination automation Verifies the factual accuracy of AI-generated content Internal library
Heuristic QA review (Lovelace) Produces a GO / GO_WITH_WARNINGS / NO_GO verdict on the quality of a deliverable; can block a deployment (./ship) Command-line interface / control gate
Test plan executor Runs the pre-production test plan via an automated browser (Playwright) Command-line interface
Active automation classifier Identifies and classifies all Python automations currently running on the platform Command-line interface

SEO audits and site monitoring

Component Role Invocation mode
Blog cannibalisation radar Detects duplicates and near-duplicate semantic matches between blog articles Scheduler
Sitemap health audit Verifies sitemap integrity and alerts the Otlet agent in case of anomaly Scheduler
Internal linking audit Analyses the SEO internal link structure and detects links returning a 404 error Scheduler
Multi-tenant i18n SEO audit Checks, for each active client and each configured language, SEO metadata coverage (title, description, slug) Scheduler
Uptime monitor Performs regular HTTP checks against client sites in production Scheduler
Monitoring report Produces a comprehensive JSON report of platform status; triggered by the /status skill Scheduler / agent skill
Multi-tenant smoke test Performs a rapid HTTP check across all client sites; fails if an HTTP 500 or higher response is detected Command-line interface
Smoke test plan generator Produces a YAML configuration file describing the hub routes to monitor Command-line interface

Drift and internal consistency audits

Component Role Invocation mode
Persona drift detector Compares declared personas against the effective configuration of the technology stack; triggered by the /audit-personas skill Command-line interface / agent skill
Lexical registry auditor Inspects the platform lexical registry across three classes: term missing from the database, divergent enumeration, forbidden synonym — strict read-only mode; triggered by /audit-lexicon Command-line interface / agent skill

Visual QA

The visual QA system captures screenshots via a headless browser, then submits those images to a multimodal language model which issues a verdict on visual conformance against the declared intent of the page.

Component Role Invocation mode
Visual QA engine Headless Chromium capture + multimodal LLM verdict on the visual intent of a page Command-line interface / library
Post-deployment visual smoke test Runs a rapid visual check across all client sites after each deployment; non-blocking, reports failures without halting the process Command-line interface

Entropy detector

The entropy detector is a scheduled scanner whose mission is to identify orphaned scripts: automations that are no longer referenced by any known trigger (neither scheduler nor dispatcher). When a script is detected as orphaned, it is recorded in a pruning-candidate registry, with an observation counter and a mandatory quarantine period before any decision is made.

Precautionary principle: the detector performs no deletions. It produces only a daily report for the responsible agents, who decide manually. An immunity mechanism allows certain scripts to be explicitly protected from flagging. A weekly ritual invites the team to ask: "What have we built that we would remove today?"

The detector runs on two distinct scheduled entries: one for the orphan detection scan, and a second for generating and sending the entropy report.

Post-deployment control

Component Role Invocation mode
Post-deployment health check Checks platform status after a ./ship and triggers an automatic rollback if an anomaly is detected Command-line interface (post-deployment)
Process environment guard Verifies after each deployment that a critical service process is active on the target VPS Command-line interface

Memory, Scars and Learning Family

This family groups the components responsible for the system's persistent memory, capitalisation on past errors (scars) and continuous learning across sessions. It is organised around three complementary memory levels: structured files, an indexed note base, and a semantic vector search engine.

Main Components

Component Role Invocation mode
Scar collector Automated harvesting of scars from the versioning history Scheduled (cron)
Scar feedback loop Processes each scar in an agent loop to extract the corresponding lesson Internal library
Scar re-qualifier Batch LLM classification: reassigns the category and severity of each scar Scheduled (cron)
Scar injector (session start) Reconnects active memory at agent session startup Startup hook
Scar injector (agent spawn) Injects relevant scars when a sub-agent is launched Agent pre-tool hook
Scar injector (file edit) Injects relevant scars before any write or edit operation Edit pre-tool hook
Scar indicator refresh Recomputes aggregated scar metrics on a daily basis Scheduled (cron)
Scar report generator Produces a structured report and an email draft following an agent verdict Command line / dedicated skill
Learning engine LLM engine producing improvement suggestions for scars classified as "learnable" Internal library
Post-project lesson generator Writes a structured pedagogical lesson at the end of a project (retrospective) Command line / dedicated skill
Nightly memory consolidation Consolidates and reorganises the day's memory (Phase 5 of the memory cycle) Scheduled (nightly cron)
Semantic recall Vector-similarity search over persistent memory (RAG Phase 3) Command line / /recall skill
User profile loader Loads a segment of the user model from the profile table Internal library
Embedding synchroniser Keeps semantic memory vectors up to date (Phase 3) Scheduled (cron)
Note indexer Indexes the Zettelkasten note base into the semantic search table Scheduled (cron)
Bidirectional note synchroniser Synchronises notes every 30 minutes between the workstation (Obsidian) and the remote repository, and pushes agent-produced outputs Scheduled (cron)
Session indexer Indexes agent session transcripts into the sessions table Scheduled (cron)
Skill indexer Indexes skill cards into the skills table Scheduled (cron)
Automatic skill generator Proposes new skill cards each time a detected agent victory is recorded Worker
Skill proposal detector Autonomously creates skill proposals following the Hermes pattern Scheduled (cron)
Skill proposal monitor Alerts the founder when skill proposals are awaiting validation Scheduled (cron)
Skill template generator Automatically produces a normalised skill card from a victory pattern Internal library
Memory metrics collector Collects persistent memory metrics daily and updates the memory dashboard Scheduled (cron)
Context budget estimator Estimates in real time the context budget consumed during a session Internal library / /context-status skill
Context tracking hook Automatically records context consumption after each tool use Post-tool hook
Context tracking shell wrapper Shell variant of the preceding hook; dispatches by tool type to the estimator. ⚠ Wiring to be confirmed: the Python version is the active reference. Post-tool hook (⚠ to be confirmed)
Immutable block validator Loading and validation of the immutable block manifest (hard floor P0) — guarantees that certain critical content cannot be overwritten Internal library / /audit-hard-floor skill
Automatic detection layer Cross-cutting detections triggered during agent sessions Internal library
Session start checks Runs Phase 0 controls at session startup. ⚠ Not wired as an automatic hook: must be launched manually from the command line. Command line
Session end checks Runs session-closing controls. ⚠ Not wired as an automatic hook. The effective safeguard against unvalidated commits at session end is provided by a separate shell script triggered on the Stop event. Command line
Agent training engine Structured spartan training of agents on targeted scenarios Command line
The Review Collective agent retrospective in "Place des Armes" format (periodic debrief) Command line / /revue skill
Portrait generator Generates portrait prompts in the Harcourt style for agents Command line
Category applicator Atomically applies category slugs from a JSON proposal to the category language table Command line
Nightly health check Evaluates four system dimensions (proprioception, technical debt, learning, automata) and produces a health report. Exit codes: 0 = nominal, 1 = warning, 2 = critical. Scheduled (cron) / command line
Documentation maintenance orchestrator Orchestrates, in a single daily cron job (05:00), the 12 steps of the documentation maintenance and regeneration loop (see sub-section below). Scheduled (cron 05:00)
Semantic recall non-regression evaluation Measures recall@k and MRR@10 of the semantic recall function against a frozen baseline; exits with an error if a regression is detected Command line
Public scar publisher Prepares and publishes selected scars to the public site, with a human validation gate (--activate) Scheduled (cron) / command line / dedicated skill
Scar injector at agent spawn Addresses the harness asymmetry: when a sub-agent is launched, it receives the synchronised cognitive frame but not the scars automatically. This component performs a vector similarity search (threshold 0.45) and produces a "Previously learned pitfalls" block ready to be injected into the launch prompt. Internal library

Automated Documentation Maintenance

The system incorporates a documentation maintenance and self-repair loop that runs autonomously every night. The daily orchestrator (triggered at 05:00) chains 12 steps in a deterministic order, under an exclusive lock and with an emergency switch activatable from the database.

Update of 14 June 2026: three new steps have been added to the loop — system organ proprioception, inter-organ relationship graph computation, and publication of those organs to the public site. The loop now covers both documentation and the functional anatomy of the system.

The 12 steps of the nightly loop

# Step Description Timeout
1 Perceive Documentation drift detection — read-only, fidelity mirror between internal documentation and code state 300 s
2 Coverage Blind-spot detection — read-only, inventories undocumented components 180 s
3 Anatomy Organ proprioception: compares the declared status of each organ to its actual state (active/inactive). Automatic reversible correction only in the downgrade direction (never autonomous promotion); promotions are proposed, never applied automatically. 120 s
4 Organ graph Idempotent derivation of inter-organ relationship edges (read-only, deterministic upsert) 30 s
5 Repair Mechanical resolution of dead references in the documentation: for each dead path, resolution by base name — a unique match triggers a deterministic rewrite and commit; zero or multiple matches trigger a report and an alert, with no modification. 180 s
6 Regenerate Autonomous deep regeneration: a headless agent rewrites the internal documentation chapter and produces the corresponding public HTML. The commit is reversible. Before publication, content passes through the leak detection gate (Mitnick agent): if clean, it is published automatically; if a leak is detected, publication is blocked and the founder is alerted. Configured budget + 1800 s
7 Propose Queues remaining chapters for regeneration and prepares a summary email draft for the founder 1800 s
8 Publish documentation Stages the fresh drift and then automatically activates chapters passing all machine gates (leak, anti-guru, drift). If blocked, the founder receives an alert. 2400 s
9 Publish organs Synchronises system organs from the mother ship to the public site (update or insert with inactive status by default); anti-leak gates active. 60 s
10 Re-perceive Second drift detection pass, performed after regeneration and publication. This double pass ensures that the health snapshot pushed to the public site reflects the final state rather than the pre-regeneration state. 300 s
11 Heal Health check across four dimensions (proprioception, technical debt, learning, automata), computed on the final post-regeneration and post-publication state 240 s
12 Publish health snapshot Synchronises the health and drift snapshot to the maintenance dashboard on the public site. Best-effort mode: a return code of 2 indicates that the public VPS is unreachable, without blocking the loop. 60 s

Return codes: codes 1 and 2 from sub-steps indicate states (drift present, critical health), not failures. The orchestrator only exits with an error on a true crash (negative code). The mechanical self-repair module retains its own scheduled cadence (every 6 hours), independent of the main loop. The external review processing module runs every 30 minutes and, since the update of 7 June 2026, signals regeneration to the orchestrator rather than triggering it directly (decoupling).

Documentation loop components

Component Role Invocation mode
Documentation drift detector Proprioception mirror: detects code files more recent than their documentation, dead references, and stale public chapters — read-only Scheduled (nightly) / command line
Mechanical self-repair module Automatically corrects three classes of reversible, gated problems: (1) dead catalogue reference resolvable by unique base name, (2) broken Markdown link resolvable by unique base name, (3) missing EN navigation stub when the FR chapter is published. Any class absent from the registry is automatically rejected (fail-closed gate). Requires the --live flag to write. Scheduled (every 6 h) / command line
Dead reference resolver Deterministic resolution of dead paths in internal documentation: unique match → rewrite + commit; zero or multiple matches → report + founder alert, no modification Scheduled (via orchestrator, step 5) / command line
Regeneration cycle manager Stages drifted chapters, applies the anti-leak gate, drives deep regeneration, and prepares the founder email draft Scheduled / command line
Deep regeneration engine Launches a headless agent that rewrites a documentation chapter, reversible commit, publishes after anti-leak gate validation. Read-only by default (--live required to write). Scheduled / command line
Documentation publisher Sanitises and stages documentation chapters to the publication database; --activate = deliberate human action; --auto-activate = automatic activation of chapters passing all machine gates, with founder alert if blocked Scheduled (03:30) / via orchestrator / command line
Health snapshot synchroniser Copies the sanitised health and drift snapshot (read-only on the mother ship) to the public site publication table, to feed the maintenance dashboard. One snapshot per day (upsert). No writes to the mother ship. Best-effort. Scheduled (via orchestrator) / command line
External review processor "The outside view": processes reviews submitted by the founder, evaluates them via a sandboxed agent with anti-injection protection, and — if the review is valid — signals regeneration to the orchestrator (decoupled since 7 June 2026). One review per run, with an emergency switch. Scheduled (every 30 min) / command line
Documentation blind-spot detector Compares the list of active system components to their coverage in the internal documentation, and produces an inventory of orphans. Read-only: inventories, creates no chapters. Scheduled / command line
External critique sorter After a chapter is regenerated, re-evaluates the valid points of an external review against the new content. Three resolution classes: point resolved by regeneration (autonomous), surviving point (escalated to the founder backlog), scope confusion (neither regeneration nor escalation — a boundary signal is produced). Built-in deduplication mechanism. Internal library (post-regeneration) / command line
Organ proprioception Compares the declared status of each organ to its actual state. Asymmetry rule: automatic reversible downgrade if an organ declared "built" is actually inactive; upgrade is only proposed, never applied automatically. Exit codes: 0 = nominal, 1 = drifts detected. Scheduled (via orchestrator) / command line
Inter-organ relationship graph Idempotently computes and updates relationship edges between system organs. Derived relationships are recomputed on each run; manual relationships are inserted once only. Controlled taxonomy: flux / compose / governs / monitors / constrains / triggers. Safeguards: writes restricted to the mother ship, rejection of labels implying volition or control, blocking of forbidden edges. Emergency switch available. Scheduled (via orchestrator) / command line
Organ publisher Synchronises system organs from the mother ship to the public site: updates public fields on existing slugs, inserts with inactive status for new slugs. Anti-leak gates active (IP/tenant/credentials scrub + leak check before write). Read-only by default (--live required). Scheduled (via orchestrator) / command line

Adaptive Immunity

The system incorporates an adaptive immunity mechanism: it detects scars that recur according to similar patterns, infers potential protective reflexes from them, and submits those reflexes for validation before any deployment. No protection rule activates on its own: the human validation circuit (Mitnick agent + founder) is mandatory.

The detection engine uses a density-based clustering algorithm (DBSCAN, cosine distance, tight parameters to avoid overly broad grouping) applied to scar embeddings. The generated proposals are stored in an inert state and are never read directly by the active reflex engine until they have been explicitly armed.

The reflex engine calibration (Gauss, June 2026) restricts triggers to file write and edit operations: proposals therefore exclusively carry this type of matcher.

Component Role Invocation mode
Recurring scar detector Identifies by clustering the families of recurring scars (28 clusters detected, purity 1.00) — read-only on embeddings and the scar table Scheduled (cron) / command line
Digest and proposal assembler Builds reflex proposals from detected clusters, submits them to the safety contract, places them in inert staging, and prepares the immunity section of the daily digest Scheduled (cron) / command line
P0 safety contract Validates each proposal before staging: action restricted to deny and warn types, scope limited to the "arm" level, pattern verified against ReDoS, proof mandatory. Never writes directly to the active reflex table. Internal library
End-of-session error detector Transcript analyser triggered at the close of each session: isolates events from the current turn, filters known benign errors. Two behaviours: (A) incorrect use of a deployment tool outside an actual execution → immediate behavioural lesson + audit trace; (B) real errors (exceptions, tracebacks) → inert reflex proposal via the safety contract. Safeguards: emergency switch, anti-recursion protection, anti-loop session marker, full graceful degradation. Exits with code 2 on case A, code 0 by default. Session end hook (priority, 15 s timeout)

Deliberation Organ

The system has a dedicated deliberation organ for managing complex or controversial decisions. When a decision is flagged as requiring deliberation, this organ

Persona / agent family — maintenance

This group of components manages the lifecycle of agent profiles: enrichment via language model, synchronisation with the agent database, generation of work sheets, and non-regression testing.

  • Persona refresh — invocable from the command line or via the dedicated skill, this component queries a language model to update an agent's profile, performs a three-way diff merge, and submits the result for review before validation.
  • Full agent profile read — aggregates profile data and the history of scars associated with a given agent.
  • Cue sequence read — extracts the expected behavioural sequence (conduct) of an agent.
  • Work sheet regeneration — rebuilds from the database the individual instruction sheets used by each agent during its interventions.
  • Portrait synchronisation — propagates agent illustration files to the appropriate working locations.
  • Persona non-regression tests — unit test suite covering the profile refresh cycle.
  • Selective auto-mode validation — verifies the correct operation of the selective automatic activation mode for agents.

Inbox / email client family

Absolute rule: no client email is sent directly by the AI. Every send operation must go through the email façade, in two stages: the draft phase (composition and review), then the send phase (actual delivery). A monitoring hook blocks any bypass attempt targeting the low-level send library. Messaging credentials (IMAP account, server, password, SMTP settings) are stored in the host system's environment variables — their values never appear in the public documentation.

Core components

  • Email client façade — single entry point for the entire send workflow: draft composition, review, delivery, archiving. No other component may send a client email without going through this entry point.
  • Guard hook — intercepts every tool call before execution (PreToolUse) and blocks any direct access to the low-level send library. The email façade is the only authorised path.
  • Inbox synchronisation — polls the inbound mail server at regular intervals and stores received emails in the message tracking table.
  • Direct fallback connection — IMAP access in degraded mode for emergency situations where the primary path is unavailable.
  • Ergonomic inbox search — retrieves an email by sender or by time range, exposed as a skill.
  • Secondary mailbox read — read-only façade for monitoring a partner mailbox distinct from the primary account.
  • Attachment antivirus scan — submits each attachment to a specialised agent (Mitnick) before any processing.
  • Contact registry feed — enriches the persons table associated with clients from incoming emails.
  • Writing tone resolution — internal library that determines the stylistic register to adopt depending on the lead or client involved.
  • Inbound tone detection — hook triggered on every prompt submission: identifies whether a known client is mentioned and silently injects the corresponding tone instructions. Has no effect if no client is detected. Anti-false-positive guards require an exact identifier; internal entities are systematically excluded.
  • Backup failure alert — immediately sends an email to the founder upon failure of an automated backup.
  • Founder cockpit notifications — pushes significant operational dashboard events by email.
  • SRE alerts — notifies by email of rollback failures and critical scars detected.
  • API budget control — compares the monthly cumulative language model call count against the allocated budget and triggers an alert on overrun.
  • Sales calendar synchronisation — imports appointments booked via the scheduling tool into the Pipeline CRM.
  • Google reviews synchronisation — retrieves and stores reviews published on the Google Business profile.
  • Freelance platform automator — manages the connection and interactions with the freelance marketplace.
  • Attachment extraction — isolates files attached to an email before forwarding them to the antivirus scanner.
  • Inbox sync cron wrapper — scheduled task that triggers inbox synchronisation via the internal API.
  • Real-time inbox monitoring — manually operated component (dedicated terminal): polls the mailbox every two minutes and signals any new client email visually and audibly.
  • Low-level inbox façade — shell wrapper for direct mailbox reading.
  • Sovereign secret vault — generates a single-use link hosted on the mothership's own infrastructure for transmitting sensitive information to a client (credentials, instructions). No third-party service is involved; no password is transmitted in plain text by email.
  • Email loop-closure guardian — detects two types of leaks in conversation threads with active client contacts:
    1. A received email with no acknowledgement beyond a configurable hourly threshold.
    2. A thread resolved internally but for which the client has never received an outbound reply.
    A sliding window prevents noise generated by historical data. The component runs as a scheduled task and offers three usage modes: draft generation, summary dispatch, or JSON export.

Family: Publishing, SEO & Content

This family groups the automations responsible for editorial production, search engine optimization, and multi-tenant content management. Each component operates in DB-first mode: it reads and writes directly to the reference tables, without going through a graphical interface.

Publication engine and SEO optimization

  • DB-first publication engine — orchestrates the creation and update of articles from the database; invocable from the command line or via the agent's /publish skill.
  • Multilingual SEO engine (single core) — optimizes metadata, descriptions, FAQ blocks, and internal linking on a page-by-page basis. This is a singleton core: no other component duplicates this logic. It records the state of each page in a dedicated status table and retains snapshots before any mutation, enabling rollback. It runs exclusively on the mothership, driven by the task scheduler.
  • Short description fixer — detects cases where a product's short description overflows into the long description field (misplaced truncation); takes a snapshot before correction and supports rollback.
  • Technical SEO sentinel — monitors key SEO indicators across all enrolled tenants and raises alerts when regressions are detected; invocable via the /seo-sentinel skill.

Editorial hygiene and enrichment

  • Automatic article cleanup — removes or corrects editorial artifacts from blog articles according to the current style guidelines.
  • Similarity library — shared module used by the publication engine to detect semantic duplicates between articles.
  • Category regenerator — rebuilds all articles within an entire category according to editorial charter v2, from the command line.
  • Retroactive FAQ injector — generates and inserts FAQ blocks into existing articles that do not yet have them.
  • Concept dictionary monitor — inspects articles to verify the presence of terms from the internal dictionary; available via the /dictionnaire skill.

Visual generation and social distribution

  • Cover image generator — automatically produces cover images for blog articles.
  • LinkedIn carousel generator — creates PDF carousels in 1,080 × 1,080 px format intended for distribution on LinkedIn.
  • Social publishing orchestrator — automates content distribution across social networks according to a scheduled calendar.
  • Instagram synchronization — paginates through the Instagram posts of an account via the Graph API and stores them in the tenant's dedicated table, in idempotent upsert mode.

Product descriptions and listings

  • Product description generator (AI) — produces enriched product descriptions using a language model (Claude), invocable from the command line.
  • Product description writer (AI) — long-form writing variant, complementary to the generator.
  • Category inline style cleaner — removes inline style attributes that pollute category descriptions.
  • Slug cleaner — corrects and normalizes category and product slugs in the URL rewriting table.
  • DLC markdown price synchronization — keeps use-by-date-specific prices up to date in the dedicated pricing table.

Reporting and advanced SEO monitoring

  • Flywheel report — generates a Flywheel model progress report for a given tenant, from the command line.
  • GEO monitor (Generative Engine Optimization) — monitors content visibility in generative search engines; runs as a scheduled task.
  • SEO coverage watchdog — detects categories lacking a meta-description or source-language (FR) description. This component fills a blind spot in the existing SEO sentinel, which only tracks translations. It exposes the /seo-coverage skill and produces a combined digest with application error alerts.
  • Bi-weekly SEO digest — delivery layer built on top of the existing SEO sentinel, without duplicating its engine. It reads the SEO health history and granular Google Search Console data, then sends a summary by email on a bi-weekly schedule. Supports --dry-run, --test, and --send modes.
  • CMS publication test — creates a test CMS article via the shop API; for validation use only.

Sub-family: Google Search Console (GSC)

The GSC integration is based on a two-layer architecture:

  1. JavaScript probes that execute in the context of the front-end rendering server, where GSC API access is available. These probes decrypt the service account credentials from environment variables and return their result as JSON on standard output — no secret appears in logs, the database, or standard output.
  2. Python orchestrators that run on the mothership, invoke the probes, and handle idempotent database writes.
  • Organic traffic probe — queries a GSC property over two rolling 28-day windows and returns a JSON object {recent, prev}.
  • Property list probe — prerequisite verification step: lists the GSC properties accessible by the service account.
  • Dimensional import probe — retrieves GSC data by triplet (date, query, page) with an API-inherent latency of approximately 2 days.
  • GSC import orchestrator — invokes the import probe and performs the idempotent upsert to the database; supports the --days 90 and --dry-run options.
  • Sitemap submission probe — submits a sitemap to Google Search Console via the API; the service account must have full access to the property.
  • Sitemap submission orchestrator — retrieves credentials from the environment, invokes the probe, and returns the JSON verdict.

Sub-family: i18n Translations (content)

A set of components handles the translation and multilingual consistency of all content surfaces.

  • UI label translation — translates FR entries in the interface translation table into English.
  • DB-first content completion — fills in missing EN fields in the main content tables.
  • Category slug translation — generates EN and DE versions of category slugs.
  • Product listing translation — translates product language fields from FR to EN.
  • Structured content block translation — translates JSON payload fields embedded in certain content entries.
  • Translation seed — inserts into the database a translation reference set defined in YAML.
  • i18n route generator — produces in DB-first mode the localized route segments from root-level categories and tenant language metadata. The output feeds the front-end build. If the database is unavailable, the system automatically falls back to a pre-configured fallback file.
  • Corrupted EN slug regenerator — deterministically rebuilds (without an LLM) degraded EN slugs from the EN product name.
  • EN internal link fixer — rewrites FR internal links embedded in EN product descriptions to their canonical EN URL, using the sitemap and the database. Unresolvable links are preserved as-is and counted.
  • EN product name re-translation — re-translates via a language model (Mistral) EN product names that remain in French, detected by the presence of diacritic characters. The slug (URL) is never modified, in order to preserve SEO.
  • Food FAQ translation — translates food data and product FAQ tables from FR to EN via Mistral, with a robust write mechanism (DELETE + INSERT) and support for the pre-production environment.
  • EN product description quality — reviews EN product descriptions and re-translates those of insufficient quality from the canonical FR source, rejecting any result where numeric quantities disappear or where the HTML structure changes.
  • Builder content re-translation — identifies EN rows in the page builder that still contain FR text or are null, and re-translates them in batch via a language model.

Family: Browser Agents

Browser agents automate interactions with third-party websites by simulating human behavior from a real workstation. The IP protection policy relies on a residential SOCKS5 proxy hosted on a dedicated VPS — rather than an anti-bot service such as CAPTCHA solving — which enables operation in graphical browser mode (headful) from a residential address. Tasks are consumed from a dedicated job queue.

  • Playwright automaton with residential egress — base library that drives a browser via Playwright by routing outbound traffic through a residential SOCKS5 proxy.
  • Headful browser worker — worker process that executes graphical browsing tasks on the designated machine.
  • Browser job queue CLI — command-line interface for submitting and inspecting pending jobs in the queue.
  • Third-party e-commerce automaton — automates interactions with a specific client's WooCommerce store.
  • Screenshot capture — takes screenshots of web pages via a headless Chromium browser; usable as a library or via CLI.
  • SSH security wrapper — SSH forced command (command= in the authorized keys file) that controls access to the browser worker from the VPS.
  • Fleet scan — inspects all active tenants to produce a consolidated fleet status report; available as a scheduled task or via CLI.

Family: Banking, Invoicing & Finance

This family covers bank synchronization, recurring invoicing, and financial activity tracking. Financial components operate strictly in read-only mode on fiscal data: they produce indicative metrics that must be validated by a qualified accountant before any decision is made.

  • Bank synchronization entry point — main scheduled task for the banking domain; invocable via the /bank skill.
  • Bank statement import — parses bank exports and applies a cross-account deduplication mechanism; available via the /bank-import skill.
  • One-off invoicing CLI — interactive interface for creating invoices and quotes on demand.
  • Recurring invoicing — daily task that automatically issues recurring invoices according to active subscriptions.
  • Reminders and reconciliation — daily task that sends overdue payment reminders and performs reconciliation between invoices and received payments.
  • Accounting history import — one-shot migration of historical data from a third-party accounting tool.
  • P0 client fix tracker — shared library for tracking priority production fixes related to clients.
  • SIRENE address attachment — enriches client records that have a SIRET number but no address by querying the SIRENE business registry.
  • FinOps engine (Pacioli) — computes in read-only mode the fiscal indicators for micro-BNC activity: collected revenue, social contributions due, provisions, personal transfers, legal thresholds, and flat-rate withholding tax status. No database writes. Results are indicative drafts to be validated with an accountant. Supports --json, --dry-run, --buffer, and --month modes.
  • FinOps automaton (Pacioli) — delivery layer on top of the FinOps engine: distributes a weekly summary every Monday morning and ad-hoc alerts (D-3 before contribution deadlines, threshold crossings at 90%, flat-rate withholding tax deadline). An anti-spam mechanism ensures a given alert is sent only once. Supports --weekly, --alerts, --test, and --dry-run modes.

Family: Brand Watch & Monitoring

This family handles brand surveillance, competitive intelligence, and visual identity quality control.

  • Visual identity QA scoring — automatically verifies the conformance of web pages to the official Synedre design tokens across four WCAG criterion categories:
    • Color contrast (WCAG 1.4.3 / 1.4.11)
    • Visible focus (WCAG 2.4.7 / 2.4.11)
    • Interactive target size (WCAG 2.5.8)
    • Semantic structure (WCAG 1.3.1 / 1.1.1 / 1.4.1)
    Accepts a URL or an HTML file as input. The --gate mode returns an error code if a blocking criterion is violated, enabling integration into a deployment pipeline. Available via the /brand-qa skill.
  • Proprietary invention SERP monitoring — monitors the visibility of Synedre's own concepts and inventions in search results.
  • Synedre competitive intelligence — benchmarks Synedre's positioning against competing multi-agent frameworks.
  • Marco Polo monitoring agent — tracks technology, competitive, and market trends across four simultaneous fronts, as a scheduled task.
  • Monitoring persistence layer — shared module providing data access for all monitoring fronts of the Marco Polo agent.
  • Automated system maintenance — applies self-maintenance patches to the Synedre system itself as a scheduled task.

Deployment, Infrastructure and Backups

Core Deployment Principles

The system distinguishes two deployment levels with strictly separated responsibilities. The production release command is reserved for the human administrator and can never be triggered by an automated agent. The application deployment command, on the other hand, is always executed by automation. On the main environment, an application deployment directly rebuilds the production service — there is no intermediate staging environment at this level.

Absolute rule before any deployment: all changes must be committed before the build is launched. Uncommitted edits are automatically discarded at build time.

Deployment Library

The library shared by all deployment scripts orchestrates the following phases:

  • Schema drift detection — compares the TypeScript migration definitions against the actual database state before the build. If a divergence is detected, the deployment is blocked by default (strict mode enabled). In application mode, additions of missing columns or tables can be applied idempotently — an absolute rule forbids any column or table deletion through this path.
  • i18n route generation — produces the JSON file of localised route segments before the UI build, without blocking the build on failure.
  • Background agent audit — checks the status of automated agents during the build phase.
  • Full delivery cycle — Nuxt build, packaging, transfer to the mothership VPS, application container restart, health check.

Deployment Scripts and Tools

Tool Role Invocation mode
Common deployment library Shared helpers: timed phases, agent audit, background git push, schema drift detection and application, i18n generation, build, transfer, restart, health check Internal library
Deployment configuration parser Reads and validates the deployment YAML configuration file, produces usable shell variables Internal library
Dependency lock guardrail Checks the consistency of critical front-end dependency versions (CSS post-processor, Nuxt framework) before the build; blocks the build if a non-compliant version is detected CLI (pre-build)
Deployment benchmark tool Measures cold and warm deployment times on the main environment CLI
Version tree checker Verifies that the working tree is clean (no uncommitted changes) before launching a deployment CLI (pre-deployment)
Safe SQL write wrapper P0 protection wrapper for any write operation on the production database; enforces explicit validation before execution CLI
Tenant initialiser Bootstraps a new tenant from a reference template CLI
Automatic VPS provisioner Automatically provisions an OVH client VPS for CodeMyShop stores CLI
Declarative tenant seeder Initialises tenant data from a YAML configuration CLI
Nginx configuration generator Pushes the web server configuration for a tenant to its client VPS. Supports two topologies:
  • Host mode (legacy) — the secret entry protection snippet is deposited separately, then the virtual host file is transferred and activated; the web server is reloaded via the system service manager.
  • Container mode (modern model) — protection is embedded directly in the virtual host file via variable substitution; the file is placed in a shared mounted volume with the container, and nginx is reloaded inside the container.
The operation is idempotent: the reload is triggered only if the configuration has actually changed. SSH connection parameters are read from the mothership environment variables.
CLI
Main entry slug rotation Regenerates the random token for the main hub's secret entry CLI
Tenant knock-gate slug rotation Regenerates the random protection token for a tenant's secret entry, updates the local configuration and propagates the new value via the nginx generator; compatible with both topologies (host and container) CLI
Schema repository synchroniser Updates the database schema snapshot used by agents for their analyses Cron / CLI
System update tool Runs a non-interactive APT update on the mothership and client VPSs CLI / /upgrade skill
Skill file reader Surgical reading of skill files with lazy loading (tier 2) CLI
OVH DNS facade Idempotently creates or updates DNS records via the OVH API (PUT if the record exists, POST otherwise), then triggers a zone refresh. OVH API keys are read from the mothership environment variables. CLI

Backups and Restore (S3 Object Storage)

Tool Role Invocation mode
Encrypted critical files backup Encrypts and transfers the Synedre system's critical configuration files to object storage CLI / cron
Tenant database → S3 backup Exports and transfers a tenant's database to object storage Cron
Local PostgreSQL → S3 backup Backs up the mothership's local PostgreSQL database to object storage Cron
Remote PostgreSQL → S3 backup Backs up a PostgreSQL database hosted on a client VPS to object storage Cron
Files → S3 backup Transfers static files to object storage Cron
Database restore from S3 Restores a tenant's database at a given date to a specified target database CLI
PostgreSQL restore from S3 Restores a PostgreSQL database from object storage CLI
Test restore from S3 Performs a monthly validation restore to verify backup integrity Cron (monthly test)
S3 lifecycle configuration Applies the retention and expiration policy to objects in object storage CLI (one-shot)
Lifecycle policy (data) JSON file describing backup expiration and transition rules Data
Backup log rotation Cleans up and archives logs produced by backup processes Cron

OSS Synchronisation, Refactoring and Migrations

Tool Role Invocation mode
OSS comment stripper Removes all comments from the open-source snapshot before publication CLI (OSS pipeline)
OSS comment translator Translates code comments from French to English in the open-source snapshot CLI (OSS pipeline)
OSS quarantine flusher Purges files placed in quarantine during the OSS publication pipeline CLI
Module-to-pack mover Moves an application module from a source location to a destination pack CLI
Module import generator Produces explicit import declarations for the module loader CLI
TypeScript dependency analyser Maps dependencies between TypeScript modules in the project CLI
Tenant configuration to fixtures extractor Converts per-tenant static configurations into JSON fixture files; once applied, the database becomes the runtime source of truth rather than static configuration files CLI (one-shot per tenant)
Zombie record cleaner Removes obsolete module records with no active reference from the database CLI (one-shot)
Generic legacy → PostgreSQL ETL Migrates data from a legacy MySQL/MariaDB database to PostgreSQL; used for data migrations when modernising stores CLI
Drizzle schema drift applicator Idempotently applies DDL migrations detected as missing (columns, tables) — never executes a DROP CLI
Per-module DDL installer Installs the database schema for a module only if that module is declared active in the relevant tenant's configuration. A module absent from the configuration creates no tables. Application is idempotent (CREATE TABLE IF NOT EXISTS, never a DROP). CLI
Table/module consistency auditor Verifies consistency between modules declared in a tenant's configuration and tables existing in the database: detects orphaned tables (module removed) and missing tables (module activated without DDL installed) CLI
SQL migration scripts Set of SQL and JSON files for targeted migrations (locks, email configuration, prospecting integration…) SQL data

Catalogue Scraping and Injection Pipeline

This pipeline orchestrates the collection and injection of an automotive parts catalogue (turbos, injectors, high-pressure pumps, additives) representing several tens of thousands of references. It is designed to run incrementally with protection against concurrent executions.

Tool Role Invocation mode
Idempotent scraping engine Crawls the sitemap of an automotive parts merchant site (~32,000 product pages). For each page, extracts via schema.org structured data: name, SKU, manufacturer reference, brand, price, availability, OEM references and compatible vehicles; completes with the HTML specification table (manufacturer, model, engine, displacement, fuel type…). Includes anti-blocking protection and runs as an incremental cron with an overlap-prevention lock. Cron / CLI
Staging catalogue injector Idempotently injects the collected catalogue into a client VPS staging environment via a secure database connection. Features:
  • Simulation mode by default (no writes without an explicit flag)
  • Rollback mode to remove a range of injected products
  • Handling of special fields (engine type, compatible vehicles, OEM labels, warranty)
  • Restriction to a list of identifiers or a safety cap
  • Deduplication against the existing catalogue
CLI

CodeMyShop Demo Seeds

Tool Role Invocation mode
Demo product importer Imports a catalogue of approximately 120 products into the CodeMyShop demo environment CLI
Demo mega-menu generator Creates a hierarchical navigation tree for the demo store CLI
Variants and attributes seed Initialises product variants and their associated attributes in the demo CLI
Shoe sizes seed Initialises size attributes (36 to 48) for shoe products in the demo CLI
Carts and orders seed Generates fictitious carts and orders to populate the demo CLI
Demo reset tool Resets the demo database to its complete reference state (seeded golden state) CLI
Project phase seed Seed specific to a project initialisation phase CLI

Monitoring, Deprecation and Tests

Tool Role Invocation mode
Session brief generator Produces a summary of the current work session (system state, recent actions, alerts) CLI
Deprecation detector unit tests Validates the behaviour of the documentation entropy detection module CLI (test)
Selective trigger mode validation Verifies that automation in selective mode behaves according to the defined rules CLI (test)
Database sandbox bridge test Performs a smoke test on the sandbox database access bridge CLI (test)
Skill exercise engine Allows the agent to practise and validate skills in a controlled environment CLI
Annotated board engine Generates illustrated documentation boards with numbering and inset frames overlaid on a base drawing via an image processing pipeline CLI
Legacy database access facade Centralises reading of connection credentials for a legacy MariaDB database from the mothership environment variables. Credentials are never hardcoded. Internal library
Legacy password vault extractor Opens a legacy KeePass vault and extracts access credentials with strict segregation: non-sensitive information is displayed, secrets are handled in memory and never written in plaintext to disk. CLI
PDF signature stamper Stamps a transparent PNG image signature onto an existing PDF document. The signature is read from a secure directory outside the repository and is never committed. The tool always writes a new output file without modifying the original, and performs no sending. CLI / /sign-pdf skill

Lifecycle Hooks: Two Configuration Files

Lifecycle hooks are distributed across two distinct configuration files, each carrying a different set of triggers. It is essential not to confuse them: one wires the high-level facades, the other orchestrates a layer of intermediate shell scripts.

First File: Facades and Direct Utilities

This local configuration file directly wires the Python facades and session utilities to lifecycle events:

  • User prompt submission — triggers inbox synchronization (incoming email check).
  • Session start — resets context tracking, injects the session brief, and loads the current session's mementos.
  • Before any Bash tool call — activates the production write guardrail, the email send guardrail, and injects mementos into the Bash context.
  • Before any file edit or write tool — also injects mementos.
  • Before any sub-agent delegation tool — injects mementos for the sub-agent.
  • After any tool call — updates the session context tracker.

The production write guardrail protects the active client's production environment. Note: explicit session start and end scripts are not wired here — session startup goes through the context tracker, session brief, and memento injector. On edit and write tools, this first file runs the memento injector; the second file (see below) adds the reflex engine on top — both hooks execute simultaneously on that same trigger.

Second File: Shell Orchestration Layer

This second file wires an entire layer of shell scripts that wrap the facades. This scope is entirely distinct from the facade catalog described previously; it constitutes a family in its own right.

Event Scripts / Components Triggered
User prompt submission Documentation schema synchronization; automatic per-client writing tone detection (max. 8 s timeout)
Before read tool Attachment opening filter (antivirus verdict required); decentralized reflex engine (max. 10 s timeout)
Before Bash tool Attachment filter; AI-initiated deployment call blocking; database mutation check; automatic pre-commit before deployment; worksite scaffold suggestion; pre-commit transcript scan (10 s); pre-worksite memory recall (30 s); documentation linkage reminder
Before edit or write tool Decentralized reflex engine (10 s)
Before sub-agent delegation Agent reactor; memento injection into sub-agent prompt (15 s); decentralized reflex engine (10 s)
Before web browsing tool Decentralized reflex engine (10 s)
Before skill invocation Skill pre-invocation (5 s)
After Bash tool Post-tool reaction logging; automatic pre-production deployment after commit (10 s)
After sub-agent delegation Agent reactor; reaction logging; sub-agent telemetry (5 s)
After edit, write, or annotation tool Session edit tracking (3 s)
After any tool (full set) CLI → dashboard bridge (10 s): mirrors interactive session activity to the active worksite dial
Session end (Stop) Current-turn error detection and adaptive immunity proposals (15 s); CLI → dashboard bridge stop (9 s); worksite lock release (3 s); end-of-session memento creation; warning if working tree is not clean (5 s); final worksite synchronization (8 s)

Important: the shell script layer (Stop events, pre-deployment, worksite cascade, etc.) is not part of the facade catalog described in previous sections — which covers only Python facades and session utilities. This is a scope to be documented separately. The true "non-empty working tree at session end" guardrail belongs to this shell layer, not to the facade session-end scripts.

Components Added Since Early 2026

  • Attachment opening filter (on Read and Bash) — blocks opening any attachment until the antivirus has returned a "clean" verdict.
  • AI-initiated deployment blocking (on Bash) — prohibits any call to the deployment command triggered by the agent itself, in accordance with the intentional asymmetry between the two production release commands.
  • Pre-worksite memory recall (on Bash, max. 30 s timeout) — loads the relevant memory context before a worksite starts.
  • Decentralized reflex engine (on Edit/Write, Read, Agent, and WebFetch/WebSearch, max. 10 s timeout per trigger) — evaluates arm-level reflex rules; on Edit/Write, it replaces direct memento injection in the second file (the first file still retains its own injector on that trigger — both execute).
  • Anti-loop backstop on reaction logging (updated mid-2026) — an iteration threshold prevents an unclosed in-progress task from capturing iterations across all subsequent sessions.
  • Session status bar — reads JSON metadata provided by the environment at each interaction and displays in real time: estimated profitability (API cost vs. value produced), context usage gauge, working tree status, and subscription quotas. Actual wiring as a statusline is to be confirmed.
  • CLI → dashboard bridge (on all tools, max. 10 s timeout; and on Stop, max. 9 s timeout) — mirrors interactive session activity to the active worksite dial via the agent event table; no effect if no worksite is linked to the current session.
  • Memento injection into sub-agents (on PreToolUse:Agent, max. 15 s timeout) — bridges the context asymmetry between the main agent and its sub-agents: prepends the "Already Learned Pitfalls" block to the sub-agent prompt via the only vector that reaches it. Relies on vector search in the memento database (configurable similarity threshold). Runs alongside the agent reactor on the same trigger.
  • End-of-turn error detection and adaptive immunity (first Stop hook, max. 15 s timeout) — analyzes current-turn errors; classifies deployment command call attempts outside execution as a violation with traceability; for genuine errors, proposes immunity lessons via the dedicated safety mechanism; exits 0 by default.
  • Automatic writing tone detection (on UserPromptSubmit, max. 8 s timeout) — identifies the target client in the prompt and automatically injects the corresponding writing tone profile; excludes internal clients from false positives; always exits 0.

Catalog Reliability Notes

  • Around twenty scripts only have a file header in the form of an author/copyright notice; their actual internal documentation appears at the fifth line and has been retrieved. No role has been fabricated.
  • One agent data audit script has no header documentation; its role was inferred from its main entry point. ⚠ To be confirmed.
  • The invocation column in the catalog mixes two levels of certainty:
    • Certain: verified presence in the scheduling table for approximately sixteen scripts (backups, indexing, log rotation, monitoring, memory metrics, notifications, pattern detection, etc.).
    • Inferred: deduced from the script name or internal documentation (mention of "daily/nightly cron").
    For scheduling ground truth, consult the system scheduling table directly. Note: the internal application scheduler has been offline since May 2026; the fallback is native Linux scheduling.
  • The mapping between declared skills and underlying facades is sourced from skill definition files; not all of them have been opened individually. ⚠ To be confirmed on a case-by-case basis.