Conversation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughAdded a new Guides section under Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Snapshot WarningsEnsure that dependencies are being submitted on PR branches. Re-running this action after a short time may resolve the issue. See the documentation for more information and troubleshooting advice. Scanned FilesNone |
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/guides/agents.md`:
- Around line 58-61: Update the note header body under "Unique agent identity"
to remove the conflicting sentence "Agent names must be unique" and replace it
with a clear statement that "Agent identity must be unique by (name, role,
department, merge_id)"; keep the following sentence about using merge_id for
multiple agents with the same role in the same department intact so the
composite-key rule is unambiguous for readers.
In `@docs/guides/budget.md`:
- Around line 55-61: The table in the Budget guide contains incorrect default
values; update the table to match the actual defaults defined in the
BudgetConfig class (BudgetConfig.total_monthly=10000.0,
BudgetConfig.currency="USD", BudgetConfig.per_task_limit=100.0,
BudgetConfig.per_agent_daily_limit=500.0) or alternatively mark the table as
"Example values" and add a note that lists the real defaults from BudgetConfig;
locate the table in docs/guides/budget.md and either replace the Default column
values with the actual defaults or add the suggested "Example values" note
beneath the table.
In `@docs/guides/company-config.md`:
- Around line 208-224: The documentation examples and field names are
inconsistent with the validation schema: replace the example and any mentions of
preferred_model and fallback with the schema-backed names
routing.rules[].model_id and routing.fallback_chain[] (and ensure individual
rule fallback uses model_id or the schema's correct key), update the YAML
examples and the field table to use model_id for rules and fallback_chain for
the chain, and make the validation section examples match these exact keys (also
apply the same fixes at the other referenced ranges).
In `@docs/guides/contributing.md`:
- Around line 53-56: Update the "## Commit Conventions" section to state that
commits targeting main must be GPG/SSH signed due to branch protection and add a
brief "How to sign" pointer (one-line summary + a link to GitHub's "signing
commits" docs or equivalent) so contributors know how to enable signing; also
apply the same wording to the later commit-related section around the other
commit guidance to ensure consistency.
In `@docs/guides/memory.md`:
- Around line 136-151: The docs table overstates supported RetrievalConfig
options: update the table so it only lists the actual, validated fields exposed
by RetrievalConfig (e.g., relevance_weight, recency_weight, default_relevance,
min_relevance, max_memories, include_shared, injection_point,
non_inferable_only) and remove or mark as unsupported fusion_strategy and rrf_k
(and any other RRF-related entries) since RetrievalConfig currently rejects
non-"linear" fusion at validation time; ensure the text clarifies that only
"linear" fusion is supported and that RRF parameters are not supported at
runtime.
- Line 125: Docs list for consolidation_interval is missing the "monthly"
option; update the table entry for `consolidation_interval` to include `monthly`
among the allowed values (e.g., `hourly`, `daily`, `weekly`, `monthly`, `never`)
and ensure the documentation text referencing the ConsolidationInterval
type/enum (`ConsolidationInterval`) matches this list so the docs reflect the
actual available option.
- Around line 67-75: The docs list memory vector/history backends (qdrant,
qdrant-external, postgresql) that don't match the runtime validation in
MemoryConfig (which currently restricts vector_store to "sqlite|pgvector" and
history_store to "sqlite"); either update the guide entries around
memory.vector_store and memory.history_store to show the actual allowed values
or update MemoryConfig to accept the documented backends—locate the MemoryConfig
type/validator and its vector_store and history_store fields and make the
allowed values consistent with the documentation (or vice versa) so users cannot
supply invalid configs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0bff1f6c-ec08-4d12-a5e7-007b47ff67eb
📒 Files selected for processing (14)
docs/getting_started.mddocs/guides/agents.mddocs/guides/budget.mddocs/guides/company-config.mddocs/guides/contributing.mddocs/guides/deployment.mddocs/guides/index.mddocs/guides/mcp-tools.mddocs/guides/memory.mddocs/guides/quickstart.mddocs/guides/security.mddocs/index.mddocs/user_guide.mdmkdocs.yml
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
🧠 Learnings (28)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Applied to files:
docs/getting_started.mddocs/guides/index.mddocs/guides/security.mddocs/guides/quickstart.mddocs/guides/company-config.mddocs/guides/agents.mddocs/guides/contributing.mddocs/guides/deployment.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mddocs/index.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/company-config.mddocs/guides/agents.mddocs/guides/memory.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
docs/getting_started.mddocs/user_guide.mddocs/index.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/company-config.mddocs/guides/agents.mddocs/guides/memory.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Applied to files:
docs/getting_started.mddocs/user_guide.mddocs/index.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/company-config.mddocs/guides/agents.mddocs/guides/contributing.mddocs/guides/memory.mddocs/guides/deployment.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/company-config.mddocs/guides/agents.mddocs/guides/memory.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/company-config.mddocs/guides/agents.mddocs/guides/memory.md
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/company-config.mddocs/guides/agents.mddocs/guides/memory.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
docs/guides/security.mddocs/guides/company-config.mddocs/guides/agents.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/security/**/*.py : Security package (security/): SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Security: SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies: disabled/weighted/per-category/milestone), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume).
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-31T12:07:37.367Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T12:07:37.367Z
Learning: Update the relevant `docs/design/` page to reflect new reality when approved deviations occur
Applied to files:
docs/guides/company-config.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/hr/**/*.py : HR package (hr/): hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, LLM calibration, collaboration overrides, trend detection), promotion/demotion (criteria evaluation, approval strategies, model mapping)
Applied to files:
docs/guides/company-config.mddocs/guides/agents.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Applied to files:
docs/guides/company-config.mddocs/guides/agents.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/hr/**/*.py : HR engine must provide: hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, trend detection), promotion/demotion
Applied to files:
docs/guides/agents.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget package (budget/): cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError)
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget tracking includes pre-flight/in-flight checks, auto-downgrade, billing periods, cost tiers, quota/subscription. CFO includes anomaly detection, efficiency analysis, downgrade recommendations.
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Budget: Cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError).
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-15T12:00:18.113Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T12:00:18.113Z
Learning: Commits: <type>: <description> — types: feat, fix, refactor, docs, test, chore, perf, ci. Enforced by commitizen (commit-msg hook). Signed commits: required on main via branch protection — all commits must be GPG/SSH signed.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Version bumping (pre-1.0): `fix:` = patch, `feat:` = patch, `feat!:` = minor, `BREAKING CHANGE` trailer = minor. Update version in `pyproject.toml` (`[tool.commitizen].version`) and `src/synthorg/__init__.py` (`__version__`)
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T12:07:37.364Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T12:07:37.364Z
Learning: Applies to **/*.py : Always read the relevant `docs/design/` page before implementing any feature or planning any issue
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/memory/**/*.py : Memory package (memory/): pluggable MemoryBackend protocol, backends/ (Mem0 adapter), retrieval pipeline (ranking, RRF fusion, injection, formatting, non-inferable filtering), shared org memory (org/), consolidation/archival (density-aware: DensityClassifier, AbstractiveSummarizer, ExtractivePreserver, DualModeConsolidationStrategy)
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/memory/**/*.py : Use MemoryBackend protocol with pluggable backends (Mem0 adapter available at backends/mem0/) for persistent agent memory
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-15T18:17:43.675Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:17:43.675Z
Learning: Applies to docker/{Dockerfile*,compose.yml} : Docker: Backend uses 3-stage build (builder → setup → distroless runtime), Chainguard Python, non-root (UID 65532), CIS-hardened. Web uses nginxinc/nginx-unprivileged, Vue 3 SPA with PrimeVue + Tailwind CSS, SPA routing, API/WebSocket proxy to backend.
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile.sandbox : Docker sandbox: `synthorg-sandbox` — Python 3.14 + Node.js + git, non-root (UID 10001), agent code execution sandbox
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/docker.yml : Docker workflow: builds backend + web + sandbox images, pushes to GHCR, signs with cosign. SLSA L3 provenance attestations via actions/attest-build-provenance. Scans: Trivy (CRITICAL = hard fail, HIGH = warn) + Grype (critical cutoff) + CIS Docker Benchmark v1.6.0 compliance (informational). CVE triage via .github/.trivyignore.yaml and .github/.grype.yaml. Images only pushed after scans pass. Triggers on push to main and version tags (v*).
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to Dockerfile* : Backend images must use Chainguard distroless with non-root user; web image must use nginx-unprivileged with non-root user; sandbox image must use Python + Node.js with non-root user. All Docker files in `docker/` -- Dockerfiles, compose, `.env.example`. Single root `.dockerignore`. All images build with `context: .`
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile : Docker: 3-stage build (builder → setup → distroless runtime) for backend, Chainguard Python, non-root (UID 65532), CIS-hardened
Applied to files:
docs/guides/deployment.md
🪛 LanguageTool
docs/guides/index.md
[style] ~9-~9: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1824 characters long)
Context: ...t Tutorial if you are new to SynthOrg. !!! tip "New to SynthOrg?" Start with ...
(EN_EXCESSIVE_EXCLAMATION)
docs/guides/security.md
[style] ~339-~339: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...ire output (fail-closed) | | Log only | log_only | Log findings but pass output through...
(ADVERB_REPETITION_PREMIUM)
docs/guides/budget.md
[style] ~126-~126: Using many exclamation marks might seem excessive (in this case: 9 exclamation marks for a text that’s 5158 characters long)
Context: ...es apply (always at task assignment) | !!! tip "Downgrades never happen mid-execut...
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.22.0)
docs/index.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/quickstart.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 44-44: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 113-113: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 117-117: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/company-config.md
[warning] 210-210: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 337-337: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 361-361: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 375-375: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
docs/guides/agents.md
[warning] 210-210: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
docs/guides/contributing.md
[warning] 210-210: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
docs/guides/memory.md
[warning] 115-115: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 265-265: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (10)
docs/getting_started.md (1)
168-168: LGTM! Good addition to contributor resources.The new Contributing Guide link provides an additional entry point for developers, complementing the existing CONTRIBUTING.md (branch/PR workflow) and CLAUDE.md (code conventions) references.
docs/index.md (1)
34-40: LGTM! Guides card properly integrated.The new Guides card follows the established pattern and provides clear navigation to the comprehensive guide collection. The icon choice and description are appropriate.
docs/user_guide.md (1)
117-117: LGTM! Guides link properly placed.The Guides link is appropriately positioned in the Next Steps section and accurately describes the guide collection content.
docs/guides/index.md (1)
1-90: LGTM! Well-structured guides landing page.The landing page provides clear navigation to all guide topics with appropriate icons and descriptions. The frontmatter is properly formatted, and the tip callout effectively directs new users to the quickstart tutorial.
mkdocs.yml (1)
105-115: LGTM! Guides navigation properly structured.The new Guides section is correctly positioned in the site navigation and includes all 10 guide entries with consistent titles and proper indentation.
docs/guides/security.md (1)
1-352: LGTM! Comprehensive and accurate security guide.The guide provides excellent coverage of SynthOrg's security configuration with clear examples and explanations. All documented configuration fields, enum values, and YAML examples match the actual implementation in
src/synthorg/security/config.pyandsrc/synthorg/security/models.py. The structure is logical, progressing from autonomy levels through trust strategies to custom policies and output scanning.docs/guides/quickstart.md (1)
1-179: LGTM! Excellent quickstart tutorial.The tutorial provides a clear, step-by-step path to running a first synthetic organization. Technical details (ports, CLI commands, authentication) are accurate and consistent with other documentation. The Mermaid diagrams effectively illustrate the organization structure and task processing flow. The progression from installation through first task submission is well-paced for a 5-minute quickstart.
docs/guides/budget.md (1)
1-241: Comprehensive budget guide with accurate architecture.Aside from the default values issue flagged above, the guide provides excellent coverage of SynthOrg's budget enforcement system. The three-layer architecture (pre-flight, in-flight, task-boundary), alert thresholds, auto-downgrade behavior, and API endpoints are all accurately documented and match the implementation in
src/synthorg/budget/. The scenario walkthrough (lines 225-234) is particularly helpful for understanding the system behavior.docs/guides/mcp-tools.md (1)
76-96: MCP guide is consistent with implementation details.Field coverage, filter overlap constraint, and SecOps/category behavior align with the current MCP config and bridge model behavior.
Also applies to: 139-142, 206-212
docs/guides/deployment.md (1)
58-83: Deployment guide aligns well with current Docker implementation.Environment defaults, health checks, runtime hardening controls, network topology, and image verification flow are accurately documented.
Also applies to: 96-127, 167-173, 187-199
| !!! note "Unique agent identity" | ||
|
|
||
| Agent names must be unique within the organization. Uniqueness is determined by the composite key of `(name, role, department, merge_id)`. Use `merge_id` when you need multiple agents with the same role in the same department. | ||
|
|
There was a problem hiding this comment.
Clarify uniqueness wording in the note.
“Agent names must be unique” conflicts with the composite-key rule immediately after it. Please reword to “agent identity must be unique by (name, role, department, merge_id)”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/agents.md` around lines 58 - 61, Update the note header body
under "Unique agent identity" to remove the conflicting sentence "Agent names
must be unique" and replace it with a clear statement that "Agent identity must
be unique by (name, role, department, merge_id)"; keep the following sentence
about using merge_id for multiple agents with the same role in the same
department intact so the composite-key rule is unambiguous for readers.
| | Field | Type | Default | Description | | ||
| |-------|------|---------|-------------| | ||
| | `total_monthly` | float | `100.0` | Monthly budget limit. Set to `0` to disable enforcement. | | ||
| | `currency` | string | `"EUR"` | ISO 4217 currency code for display | | ||
| | `reset_day` | int | `1` | Day of the month the budget resets (1--28) | | ||
| | `per_task_limit` | float | `5.0` | Maximum cost allowed per individual task | | ||
| | `per_agent_daily_limit` | float | `10.0` | Maximum cost per agent per day | |
There was a problem hiding this comment.
Incorrect default values in Budget Fields table.
The "Default" column values do not match the actual implementation in src/synthorg/budget/config.py:
| Field | Guide Claims | Actual Default |
|---|---|---|
total_monthly |
100.0 |
10_000.0 |
currency |
"EUR" |
"USD" |
per_task_limit |
5.0 |
100.0 |
per_agent_daily_limit |
10.0 |
500.0 |
Based on learnings, the BudgetConfig class defines these defaults in src/synthorg/budget/config.py. The guide appears to be using example values suitable for a small team rather than the actual defaults.
📝 Proposed fix: use actual defaults or clarify as examples
Option 1: Show actual defaults
| Field | Type | Default | Description |
|-------|------|---------|-------------|
-| `total_monthly` | float | `100.0` | Monthly budget limit. Set to `0` to disable enforcement. |
-| `currency` | string | `"EUR"` | ISO 4217 currency code for display |
+| `total_monthly` | float | `10000.0` | Monthly budget limit. Set to `0` to disable enforcement. |
+| `currency` | string | `"USD"` | ISO 4217 currency code for display |
| `reset_day` | int | `1` | Day of the month the budget resets (1--28) |
-| `per_task_limit` | float | `5.0` | Maximum cost allowed per individual task |
-| `per_agent_daily_limit` | float | `10.0` | Maximum cost per agent per day |
+| `per_task_limit` | float | `100.0` | Maximum cost allowed per individual task |
+| `per_agent_daily_limit` | float | `500.0` | Maximum cost per agent per day |Option 2: Relabel as example values
-### Budget Fields
+### Budget Fields (Example Configuration)
-| Field | Type | Default | Description |
+| Field | Type | Example | Description |Add a note below the table:
!!! note "Example values"
The values shown above are examples for a small team. Actual defaults are: `total_monthly=10000.0`, `currency="USD"`, `per_task_limit=100.0`, `per_agent_daily_limit=500.0`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Field | Type | Default | Description | | |
| |-------|------|---------|-------------| | |
| | `total_monthly` | float | `100.0` | Monthly budget limit. Set to `0` to disable enforcement. | | |
| | `currency` | string | `"EUR"` | ISO 4217 currency code for display | | |
| | `reset_day` | int | `1` | Day of the month the budget resets (1--28) | | |
| | `per_task_limit` | float | `5.0` | Maximum cost allowed per individual task | | |
| | `per_agent_daily_limit` | float | `10.0` | Maximum cost per agent per day | | |
| | Field | Type | Default | Description | | |
| |-------|------|---------|-------------| | |
| | `total_monthly` | float | `10000.0` | Monthly budget limit. Set to `0` to disable enforcement. | | |
| | `currency` | string | `"USD"` | ISO 4217 currency code for display | | |
| | `reset_day` | int | `1` | Day of the month the budget resets (1--28) | | |
| | `per_task_limit` | float | `100.0` | Maximum cost allowed per individual task | | |
| | `per_agent_daily_limit` | float | `500.0` | Maximum cost per agent per day | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/budget.md` around lines 55 - 61, The table in the Budget guide
contains incorrect default values; update the table to match the actual defaults
defined in the BudgetConfig class (BudgetConfig.total_monthly=10000.0,
BudgetConfig.currency="USD", BudgetConfig.per_task_limit=100.0,
BudgetConfig.per_agent_daily_limit=500.0) or alternatively mark the table as
"Example values" and add a note that lists the real defaults from BudgetConfig;
locate the table in docs/guides/budget.md and either replace the Default column
values with the actual defaults or add the suggested "Example values" note
beneath the table.
| Rules are evaluated in order. Each rule matches by `role_level` and/or `task_type`: | ||
|
|
||
| ```yaml | ||
| routing: | ||
| strategy: cost_aware | ||
| rules: | ||
| - role_level: c_suite | ||
| preferred_model: "large" | ||
| - role_level: senior | ||
| preferred_model: "medium" | ||
| fallback: "small" | ||
| - task_type: review | ||
| preferred_model: "small" | ||
| fallback_chain: | ||
| - "medium" | ||
| - "small" | ||
| ``` |
There was a problem hiding this comment.
Routing rule field names are out of sync with the schema (model_id vs preferred_model/fallback).
Current config validation expects routing.rules[].model_id plus routing.fallback_chain[] references. The example, field table, and validation section document different keys, which will mislead users into invalid YAML.
Proposed doc fix
routing:
strategy: cost_aware
rules:
- role_level: c_suite
- preferred_model: "large"
+ model_id: "cloud.example-large-001"
- role_level: senior
- preferred_model: "medium"
- fallback: "small"
+ model_id: "cloud.example-medium-001"
- task_type: review
- preferred_model: "small"
+ model_id: "cloud.example-small-001"
fallback_chain:
- - "medium"
- - "small"
+ - "cloud.example-medium-001"
+ - "cloud.example-small-001"
@@
-| `preferred_model` | string | *(required)* | Preferred model alias or ID |
-| `fallback` | string | `null` | Fallback model |
+| `model_id` | string | *(required)* | Target model reference |Also applies to: 226-232, 393-395
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 210-210: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/company-config.md` around lines 208 - 224, The documentation
examples and field names are inconsistent with the validation schema: replace
the example and any mentions of preferred_model and fallback with the
schema-backed names routing.rules[].model_id and routing.fallback_chain[] (and
ensure individual rule fallback uses model_id or the schema's correct key),
update the YAML examples and the field table to use model_id for rules and
fallback_chain for the chain, and make the validation section examples match
these exact keys (also apply the same fixes at the other referenced ranges).
| ```yaml | ||
| memory: | ||
| backend: "mem0" | ||
| level: session | ||
| storage: | ||
| data_dir: "/data/memory" | ||
| vector_store: "qdrant" | ||
| history_store: "sqlite" | ||
| options: |
There was a problem hiding this comment.
Storage backend values/defaults don’t match the actual schema.
The guide documents qdrant/qdrant-external and postgresql, but MemoryConfig currently validates vector_store as sqlite|pgvector and history_store as sqlite only. This will lead users to invalid configs.
Proposed doc fix
- vector_store: "qdrant"
+ vector_store: "sqlite"
history_store: "sqlite"
@@
-| `data_dir` | string | `"/data/memory"` | Directory for memory data (Docker volume mount) |
-| `vector_store` | string | `"qdrant"` | Vector store: `"qdrant"` (embedded) or `"qdrant-external"` |
-| `history_store` | string | `"sqlite"` | History store: `"sqlite"` or `"postgresql"` |
+| `data_dir` | string | `"/var/lib/synthorg/memory"` | Directory for memory data |
+| `vector_store` | string | `"sqlite"` | Vector store: `"sqlite"` or `"pgvector"` |
+| `history_store` | string | `"sqlite"` | History store: `"sqlite"` |Also applies to: 107-112
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/memory.md` around lines 67 - 75, The docs list memory
vector/history backends (qdrant, qdrant-external, postgresql) that don't match
the runtime validation in MemoryConfig (which currently restricts vector_store
to "sqlite|pgvector" and history_store to "sqlite"); either update the guide
entries around memory.vector_store and memory.history_store to show the actual
allowed values or update MemoryConfig to accept the documented backends—locate
the MemoryConfig type/validator and its vector_store and history_store fields
and make the allowed values consistent with the documentation (or vice versa) so
users cannot supply invalid configs.
| |-------|------|---------|-------------| | ||
| | `retention_days` | int or null | `null` | Days to retain memories (`null` = forever) | | ||
| | `max_memories_per_agent` | int | `10000` | Upper bound on memories per agent | | ||
| | `consolidation_interval` | string | `"daily"` | How often to consolidate: `hourly`, `daily`, `weekly`, `never` | |
There was a problem hiding this comment.
monthly consolidation interval is missing from the documented options.
ConsolidationInterval includes monthly; docs currently list only hourly, daily, weekly, never.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/memory.md` at line 125, Docs list for consolidation_interval is
missing the "monthly" option; update the table entry for
`consolidation_interval` to include `monthly` among the allowed values (e.g.,
`hourly`, `daily`, `weekly`, `monthly`, `never`) and ensure the documentation
text referencing the ConsolidationInterval type/enum (`ConsolidationInterval`)
matches this list so the docs reflect the actual available option.
| | Field | Type | Default | Description | | ||
| |-------|------|---------|-------------| | ||
| | `strategy` | string | `"context"` | Injection strategy (currently only `"context"`) | | ||
| | `relevance_weight` | float | `0.7` | Weight for backend relevance score (0.0--1.0) | | ||
| | `recency_weight` | float | `0.3` | Weight for recency decay score (0.0--1.0) | | ||
| | `recency_decay_rate` | float | `0.01` | Exponential decay rate per hour | | ||
| | `personal_boost` | float | `0.1` | Boost for personal memories over shared (0.0--1.0) | | ||
| | `min_relevance` | float | `0.3` | Minimum combined score to include a memory | | ||
| | `max_memories` | int | `20` | Maximum memories to inject (1--100) | | ||
| | `include_shared` | bool | `true` | Whether to query shared org memory | | ||
| | `default_relevance` | float | `0.5` | Score for entries missing a relevance score | | ||
| | `injection_point` | string | `"system"` | Where to inject: `"system"` (system prompt) or `"user"` | | ||
| | `non_inferable_only` | bool | `false` | Only inject memories tagged as non-inferable | | ||
| | `fusion_strategy` | string | `"linear"` | Ranking fusion: `"linear"` (currently supported) | | ||
| | `rrf_k` | int | `60` | RRF smoothing constant (only with RRF strategy, 1--1000) | | ||
|
|
There was a problem hiding this comment.
Retrieval field reference overstates currently supported config.
RetrievalConfig currently exposes relevance_weight, recency_weight, fusion_strategy, and rrf_k, and rejects non-linear fusion at validation time. The table includes additional fields and implies RRF runtime support, which is inconsistent.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/memory.md` around lines 136 - 151, The docs table overstates
supported RetrievalConfig options: update the table so it only lists the actual,
validated fields exposed by RetrievalConfig (e.g., relevance_weight,
recency_weight, default_relevance, min_relevance, max_memories, include_shared,
injection_point, non_inferable_only) and remove or mark as unsupported
fusion_strategy and rrf_k (and any other RRF-related entries) since
RetrievalConfig currently rejects non-"linear" fusion at validation time; ensure
the text clarifies that only "linear" fusion is supported and that RRF
parameters are not supported at runtime.
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive set of documentation guides for SynthOrg, covering topics such as agent roles, budget control, company configuration, security policies, tool integration (MCP), deployment, memory management, and contributing guidelines. The documentation is well-structured and provides clear examples for complex configurations. I have provided feedback on clarifying the model field description in the agent guide, explicitly defining budget alert percentages, ensuring consistent terminology for agent identity, and emphasizing the confidentiality of secrets in the deployment guide.
docs/guides/agents.md
Outdated
| | `level` | SeniorityLevel | `mid` | Seniority level (see table below) | | ||
| | `personality` | dict | `{}` | Raw personality config injected into the system prompt | | ||
| | `personality_preset` | string | `null` | Named personality preset (see [Personality](#personality-presets)) | | ||
| | `model` | string or dict | *(from routing)* | Model assignment -- string alias or structured config | |
There was a problem hiding this comment.
The model field is described as string or dict in the table, but the description says it can be a string alias or structured config. For clarity and consistency with the examples provided later in the guide (lines 244-265), it would be better to explicitly mention that the dictionary form allows for fine-grained control over tier, priority, and context constraints.
|
|
||
| !!! warning "Threshold ordering" | ||
|
|
||
| Thresholds must be strictly ordered: `warn_at < critical_at < hard_stop_at`. Violating this produces a validation error at config load time. |
There was a problem hiding this comment.
The validation rule warn_at < critical_at < hard_stop_at is a critical constraint for the budget system to function correctly. It might be beneficial to explicitly state that these values represent percentages of the total_monthly budget to avoid any ambiguity.
docs/guides/company-config.md
Outdated
|
|
||
| | Rule | Description | | ||
| |------|-------------| | ||
| | Unique agent names | Agent composite key (name + role + department + merge_id) must be unique | |
There was a problem hiding this comment.
The validation rule for unique agent names mentions a composite key of (name, role, department, merge_id). Ensure that the documentation consistently refers to this composite key when discussing agent identity to prevent users from assuming only the name field must be unique.
docs/guides/deployment.md
Outdated
|
|
||
| | Variable | Description | | ||
| |----------|-------------| | ||
| | `SYNTHORG_JWT_SECRET` | JWT signing secret. Must be >= 32 characters of URL-safe base64. Generate: `python -c "import secrets; print(secrets.token_urlsafe(48))"` | |
There was a problem hiding this comment.
The recommendation for SYNTHORG_JWT_SECRET to be at least 32 characters of URL-safe base64 is a good security practice. However, it's important to emphasize that this secret should be kept highly confidential and never committed to version control.
cc7c639 to
7964375
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/guides/agents.md (1)
64-67:⚠️ Potential issue | 🟡 MinorTemplate identity key wording is still misleading.
Line 66 should not imply
nameis part of template merge identity. Based on the merge algorithm, template agent matching is keyed by(role, department, merge_id), withmerge_idas the disambiguator for duplicate(role, department)pairs.Suggested wording update
!!! note "Unique agent identity" - Agent identity must be unique by the composite key `(name, role, department)`. When using templates with `merge_id`, the composite key extends to `(name, role, department, merge_id)`. + For template merging, agent identity is matched by `(role, department, merge_id)`. + Use `merge_id` to disambiguate multiple agents sharing the same `(role, department)` pair.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/agents.md` around lines 64 - 67, The documentation incorrectly states that template merge identity includes "name"; change the wording so it clearly states that template agent matching is keyed by (role, department, merge_id) — not (name, role, department, merge_id) — and explain that merge_id is only used to disambiguate duplicate (role, department) pairs; update the sentence referencing "merge_id" and "name" so "name" is omitted from the template merge key and include the explicit key tuple (role, department, merge_id) for clarity.docs/guides/budget.md (1)
55-61:⚠️ Potential issue | 🟠 MajorDefault values are still inconsistent with implementation.
Line 55–Line 61 and Line 161 document defaults as
EUR/100.0/5.0/10.0, which appears to conflict with the code defaults previously identified forBudgetConfig. Please update this table (and the currency note in Line 161) to the actual defaults or explicitly relabel them as examples.#!/bin/bash # Verify actual BudgetConfig defaults in source and compare with docs. set -euo pipefail echo "== Budget config defaults from source ==" fd -a "config.py" src/synthorg/budget | while read -r f; do echo "-- $f --" rg -n "total_monthly|currency|per_task_limit|per_agent_daily_limit" "$f" -n -C2 done echo echo "== Budget guide defaults in docs/guides/budget.md ==" rg -n "total_monthly|currency|per_task_limit|per_agent_daily_limit|default EUR|Default" docs/guides/budget.md -n -C1Also applies to: 161-161
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/budget.md` around lines 55 - 61, The documented default values for BudgetConfig are inconsistent with the actual implementation; update the table entries for total_monthly, currency, reset_day, per_task_limit, and per_agent_daily_limit to match the actual defaults defined on the BudgetConfig class, and also update the currency note to the real default currency (or explicitly mark all values as “examples” if you prefer not to hard-code defaults); ensure you reference the BudgetConfig class and its fields (total_monthly, currency, reset_day, per_task_limit, per_agent_daily_limit) when making the change so the docs and implementation stay synced.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/guides/agents.md`:
- Around line 64-67: The documentation incorrectly states that template merge
identity includes "name"; change the wording so it clearly states that template
agent matching is keyed by (role, department, merge_id) — not (name, role,
department, merge_id) — and explain that merge_id is only used to disambiguate
duplicate (role, department) pairs; update the sentence referencing "merge_id"
and "name" so "name" is omitted from the template merge key and include the
explicit key tuple (role, department, merge_id) for clarity.
In `@docs/guides/budget.md`:
- Around line 55-61: The documented default values for BudgetConfig are
inconsistent with the actual implementation; update the table entries for
total_monthly, currency, reset_day, per_task_limit, and per_agent_daily_limit to
match the actual defaults defined on the BudgetConfig class, and also update the
currency note to the real default currency (or explicitly mark all values as
“examples” if you prefer not to hard-code defaults); ensure you reference the
BudgetConfig class and its fields (total_monthly, currency, reset_day,
per_task_limit, per_agent_daily_limit) when making the change so the docs and
implementation stay synced.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 81da6c95-e16c-4bb7-8740-bf683c33ccfe
📒 Files selected for processing (14)
docs/getting_started.mddocs/guides/agents.mddocs/guides/budget.mddocs/guides/company-config.mddocs/guides/contributing.mddocs/guides/deployment.mddocs/guides/index.mddocs/guides/mcp-tools.mddocs/guides/memory.mddocs/guides/quickstart.mddocs/guides/security.mddocs/index.mddocs/user_guide.mdmkdocs.yml
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
docs/**/*.md: Pages CI job: version extraction from pyproject.toml, OpenAPI export, Astro + Zensical docs build with version banner, GitHub Pages deploy on push to main.
Docs: Markdown in docs/, built with Zensical. Design spec: docs/design/ (11 pages), Architecture: docs/architecture/, Roadmap: docs/roadmap/. Security: docs/security.md, Licensing: docs/licensing.md, Reference: docs/reference/.
Files:
docs/index.mddocs/getting_started.mddocs/user_guide.mddocs/guides/index.mddocs/guides/security.mddocs/guides/budget.mddocs/guides/agents.mddocs/guides/mcp-tools.mddocs/guides/company-config.mddocs/guides/quickstart.mddocs/guides/deployment.mddocs/guides/memory.mddocs/guides/contributing.md
mkdocs.yml
📄 CodeRabbit inference engine (CLAUDE.md)
Docs config: mkdocs.yml with Zensical, mkdocstrings[python], griffe-pydantic. Docs group in pyproject.toml.
Files:
mkdocs.yml
🧠 Learnings (43)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.442Z
Learning: Applies to docs/**/*.md : Docs: Markdown in docs/, built with Zensical. Design spec: docs/design/ (11 pages), Architecture: docs/architecture/, Roadmap: docs/roadmap/. Security: docs/security.md, Licensing: docs/licensing.md, Reference: docs/reference/.
📚 Learning: 2026-03-31T14:18:06.442Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.442Z
Learning: Applies to docs/**/*.md : Docs: Markdown in docs/, built with Zensical. Design spec: docs/design/ (11 pages), Architecture: docs/architecture/, Roadmap: docs/roadmap/. Security: docs/security.md, Licensing: docs/licensing.md, Reference: docs/reference/.
Applied to files:
docs/index.mddocs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to docs/**/*.md : Documentation files in `docs/` (Markdown, built with Zensical, config: `mkdocs.yml`); design spec in `docs/design/` (11 pages)
Applied to files:
docs/index.mdmkdocs.ymldocs/guides/index.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Applied to files:
docs/index.mddocs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/agents.mddocs/guides/company-config.mddocs/guides/quickstart.mddocs/guides/deployment.mddocs/guides/memory.mddocs/guides/contributing.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/index.mddocs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/agents.mddocs/guides/company-config.mddocs/guides/memory.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
docs/index.mddocs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/agents.mddocs/guides/company-config.mddocs/guides/memory.md
📚 Learning: 2026-03-31T14:18:06.443Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.443Z
Learning: Python package structure: src/synthorg/ (src layout with 11 subpackages), tests/, web/ (React 19 dashboard), cli/ (Go CLI binary). Design spec: docs/DESIGN_SPEC.md (pointer to docs/design/ pages).
Applied to files:
docs/getting_started.mddocs/guides/quickstart.mddocs/guides/deployment.mddocs/guides/contributing.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Applied to files:
docs/getting_started.mddocs/guides/index.mddocs/guides/security.mddocs/guides/agents.mddocs/guides/company-config.mddocs/guides/quickstart.mddocs/guides/deployment.mddocs/guides/contributing.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Web dashboard: see `web/CLAUDE.md` for commands, design system, and component inventory
Applied to files:
docs/getting_started.mddocs/guides/deployment.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/agents.mddocs/guides/memory.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/agents.mddocs/guides/company-config.mddocs/guides/memory.md
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/agents.mddocs/guides/memory.md
📚 Learning: 2026-03-31T14:18:06.443Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.443Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. Design spec is the starting point for architecture, data models, and behavior.
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-31T14:18:06.442Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.442Z
Learning: Applies to mkdocs.yml : Docs config: mkdocs.yml with Zensical, mkdocstrings[python], griffe-pydantic. Docs group in pyproject.toml.
Applied to files:
mkdocs.yml
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/security/**/*.py : Security package (security/): SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Security: SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies: disabled/weighted/per-category/milestone), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume).
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-15T19:14:27.144Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T19:14:27.144Z
Learning: Applies to src/synthorg/api/**/*.py : Authentication uses JWT + API key. Approval gate integration for high-risk operations.
Applied to files:
docs/guides/security.mddocs/guides/deployment.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget package (budget/): cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError)
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget tracking includes pre-flight/in-flight checks, auto-downgrade, billing periods, cost tiers, quota/subscription. CFO includes anomaly detection, efficiency analysis, downgrade recommendations.
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Budget: Cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError).
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/hr/**/*.py : HR package (hr/): hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, LLM calibration, collaboration overrides, trend detection), promotion/demotion (criteria evaluation, approval strategies, model mapping)
Applied to files:
docs/guides/agents.mddocs/guides/company-config.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/hr/**/*.py : HR engine must provide: hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, trend detection), promotion/demotion
Applied to files:
docs/guides/agents.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Applied to files:
docs/guides/agents.md
📚 Learning: 2026-03-20T08:28:32.845Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-20T08:28:32.845Z
Learning: Applies to src/synthorg/templates/**/*.py : Templates: pre-built company templates, personality presets, and builder.
Applied to files:
docs/guides/agents.md
📚 Learning: 2026-03-15T18:17:43.675Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:17:43.675Z
Learning: Applies to docker/{Dockerfile*,compose.yml} : Docker: Backend uses 3-stage build (builder → setup → distroless runtime), Chainguard Python, non-root (UID 65532), CIS-hardened. Web uses nginxinc/nginx-unprivileged, Vue 3 SPA with PrimeVue + Tailwind CSS, SPA routing, API/WebSocket proxy to backend.
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to docker/**/Dockerfile* : Docker images: backend (Chainguard distroless, non-root), web (nginx-unprivileged, SPA + API proxy), sandbox (Python + Node.js, non-root)
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-31T14:18:06.442Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.442Z
Learning: Applies to docker/Dockerfile* : Docker images: backend (Chainguard distroless, non-root), web (nginx-unprivileged, SPA + API proxy), sandbox (Python + Node.js, non-root).
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile.sandbox : Docker sandbox: `synthorg-sandbox` — Python 3.14 + Node.js + git, non-root (UID 10001), agent code execution sandbox
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/docker.yml : Docker workflow: builds backend + web + sandbox images, pushes to GHCR, signs with cosign. SLSA L3 provenance attestations via actions/attest-build-provenance. Scans: Trivy (CRITICAL = hard fail, HIGH = warn) + Grype (critical cutoff) + CIS Docker Benchmark v1.6.0 compliance (informational). CVE triage via .github/.trivyignore.yaml and .github/.grype.yaml. Images only pushed after scans pass. Triggers on push to main and version tags (v*).
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to Dockerfile* : Backend images must use Chainguard distroless with non-root user; web image must use nginx-unprivileged with non-root user; sandbox image must use Python + Node.js with non-root user. All Docker files in `docker/` -- Dockerfiles, compose, `.env.example`. Single root `.dockerignore`. All images build with `context: .`
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/memory/**/*.py : Memory package (memory/): pluggable MemoryBackend protocol, backends/ (Mem0 adapter), retrieval pipeline (ranking, RRF fusion, injection, formatting, non-inferable filtering), shared org memory (org/), consolidation/archival (density-aware: DensityClassifier, AbstractiveSummarizer, ExtractivePreserver, DualModeConsolidationStrategy)
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/memory/**/*.py : Use MemoryBackend protocol with pluggable backends (Mem0 adapter available at backends/mem0/) for persistent agent memory
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-18T08:23:08.912Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-18T08:23:08.912Z
Learning: When approved deviations occur, update the relevant `docs/design/` page to reflect the new reality.
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-15T12:00:18.113Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T12:00:18.113Z
Learning: Commits: <type>: <description> — types: feat, fix, refactor, docs, test, chore, perf, ci. Enforced by commitizen (commit-msg hook). Signed commits: required on main via branch protection — all commits must be GPG/SSH signed.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:18:06.442Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.442Z
Learning: Applies to docs/**/*.md : Pages CI job: version extraction from pyproject.toml, OpenAPI export, Astro + Zensical docs build with version banner, GitHub Pages deploy on push to main.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: GPG/SSH signed commits required on `main` via branch protection — all commits must be signed
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:18:06.443Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.443Z
Learning: Signed commits required on main via branch protection -- all commits must be GPG/SSH signed.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:18:06.443Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:06.443Z
Learning: CLA enforcement: contributor-assistant check on PRs, signatures in .github/cla-signatures.json.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to .github/cla-signatures.json : CLA check on PRs via contributor-assistant; signatures in `.github/cla-signatures.json`
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/cla-signatures.json : CLA signatures stored in .github/cla-signatures.json on the cla-signatures branch (unprotected, so the action can commit directly). CLA check via contributor-assistant/github-action on pull_request_target and issue_comment. Skips Dependabot.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Version bumping (pre-1.0): `fix:` = patch, `feat:` = patch, `feat!:` = minor, `BREAKING CHANGE` trailer = minor. Update version in `pyproject.toml` (`[tool.commitizen].version`) and `src/synthorg/__init__.py` (`__version__`)
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to src/synthorg/**/*.py : Maintain 80% minimum test coverage (enforced in CI)
Applied to files:
docs/guides/contributing.md
🪛 LanguageTool
docs/guides/index.md
[style] ~9-~9: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1824 characters long)
Context: ...t Tutorial if you are new to SynthOrg. !!! tip "New to SynthOrg?" Start with ...
(EN_EXCESSIVE_EXCLAMATION)
docs/guides/security.md
[style] ~339-~339: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...ire output (fail-closed) | | Log only | log_only | Log findings but pass output through...
(ADVERB_REPETITION_PREMIUM)
docs/guides/budget.md
[style] ~126-~126: Using many exclamation marks might seem excessive (in this case: 9 exclamation marks for a text that’s 5284 characters long)
Context: ...es apply (always at task assignment) | !!! tip "Downgrades never happen mid-execut...
(EN_EXCESSIVE_EXCLAMATION)
docs/guides/contributing.md
[style] ~233-~233: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4213 characters long)
Context: ... MkDocs Material features: admonitions (!!! note), tabs (=== "Tab"), code blocks...
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.22.0)
docs/index.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/security.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 46-46: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 236-236: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/budget.md
[warning] 65-65: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 100-100: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 129-129: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/agents.md
[warning] 65-65: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 100-100: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 129-129: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/mcp-tools.md
[warning] 36-36: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 57-57: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 141-141: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/company-config.md
[warning] 212-212: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 339-339: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 363-363: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 377-377: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
docs/guides/quickstart.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 44-44: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 113-113: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 117-117: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/deployment.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 46-46: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 236-236: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/memory.md
[warning] 65-65: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/contributing.md
[warning] 65-65: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (14)
docs/getting_started.md (1)
168-168: Good cross-link addition.This improves navigation from onboarding docs into the new Guides section.
docs/index.md (1)
34-41: Guides entry on homepage looks correct.Card content and target link are clear and consistent with the new docs IA.
docs/user_guide.md (1)
117-117: Nice Next Steps routing update.This is a clean, high-value pointer to the new in-depth guides.
mkdocs.yml (1)
105-115: Guides nav configuration is solid.Structure and target paths are consistent with the new guide pages and landing index.
docs/guides/index.md (1)
1-90: Strong guides landing page.Clear intro, good card taxonomy, and complete linkage across the new guide set.
docs/guides/security.md (1)
1-353: Comprehensive and well-structured security guide.Coverage depth and configuration examples are strong, and cross-links are well placed.
docs/guides/company-config.md (1)
210-234: Potential routing schema drift in docs (preferred_model/fallback).Please verify these keys against the runtime config model. If schema now uses
model_id(and chain-based fallback), these sections will produce invalid user configs.#!/bin/bash # Verify routing model field names from config schema/validators. set -euo pipefail echo "== Locate routing config classes/validators ==" rg -n -C3 --type=py '\bclass\s+.*Routing|fallback_chain|preferred_model|model_id|role_level|task_type\b' src echo echo "== Focused scan for routing rule fields ==" rg -n --type=py '\b(preferred_model|fallback|model_id|fallback_chain)\b' src/synthorgAlso applies to: 395-396, 502-512
docs/guides/memory.md (3)
67-75: Verify storage backend values againstMemoryStorageConfig.The documented
vector_store/history_storevalues may be broader than what runtime validation accepts. Please confirm these examples/tables match current allowed enums.#!/bin/bash # Inspect storage backend enums/validators in memory config. set -euo pipefail rg -n -C4 --type=py '\bclass\s+MemoryStorageConfig\b|vector_store|history_store|Literal\[' src/synthorg/memoryAlso applies to: 107-112, 273-280
125-125: Check whethermonthlyis a valid consolidation interval and document it if so.The listed interval options may be incomplete relative to the runtime enum.
#!/bin/bash # Verify allowed consolidation interval values. set -euo pipefail rg -n -C4 --type=py '\bConsolidationInterval\b|consolidation_interval|interval\b' src/synthorg/memoryAlso applies to: 229-229
136-151: Validate retrieval field table against the actual retrieval config schema.Please confirm every documented retrieval key is accepted at load time (especially fusion-related fields), so users don’t get config validation failures.
#!/bin/bash # Verify MemoryRetrievalConfig fields and validators. set -euo pipefail rg -n -C5 --type=py '\bclass\s+MemoryRetrievalConfig\b|fusion_strategy|rrf_k|relevance_weight|recency_weight|model_validator|field_validator' src/synthorg/memorydocs/guides/quickstart.md (1)
6-179: Well-structured quickstart and technically aligned with runtime behavior.The command flow, ports, and persistence notes are consistent with the current CLI and Docker configuration.
docs/guides/mcp-tools.md (1)
12-221: MCP reference is consistent with the implementation.Transport fields, filter validation, timeout/caching defaults, and security notes line up with the current MCP config and cache code paths.
docs/guides/contributing.md (1)
53-66: Commit policy section looks correct and complete.Great to see signed-commit enforcement and commitizen hook requirements documented explicitly for contributors.
Based on learnings: Signed commits required on main via branch protection -- all commits must be GPG/SSH signed.
docs/guides/deployment.md (1)
187-198: Image verification guidance is accurate and actionable.
--skip-verifyandSYNTHORG_SKIP_VERIFYusage is correctly documented for constrained environments.
Add 9 comprehensive user-facing guides under docs/guides/ covering the full user journey from quickstart to production deployment: quickstart tutorial, company YAML config reference, agent roles and hierarchy, budget and cost control, security and trust policies, MCP tool integration, Docker deployment, memory configuration, and contributing workflow. Update mkdocs.yml nav, docs landing page, user guide, and developer setup with cross-references. Closes #293 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix max_context default 128000 -> 200000 (company-config.md) - Clarify AgentConfig.name is required, not auto-generated - Clarify personality_preset and merge_id are template-only fields - Fix subscription auth to require subscription_token + tos_accepted_at - Fix 3 personality preset values (rapid_prototyper, strategic_planner, team_diplomat) - Note preset table shows 8 of 22 available presets - Add cost_usd base currency vs display currency clarification - Add coordination_metrics to Root Config table - Reword agent identity uniqueness note for clarity - Add signed-commit requirement to contributing guide - Add JWT secret confidentiality note to deployment guide Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The RootConfig validator checks uniqueness by name only (not a composite key). Template merge identity is (role, department, merge_id). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
7964375 to
86fa139
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/guides/budget.md`:
- Around line 143-146: The docs claim alias targets are validated against the
configured providers but the AutoDowngradeConfig class lacks that check; update
AutoDowngradeConfig (in src/synthorg/budget/config.py) to validate that every
alias target referenced in its aliases exists in the providers configuration
(e.g., by adding a pydantic root_validator or explicit validate() method that
receives the providers dict), and raise a clear validation error when an alias
references a model not present in providers; ensure this validation runs during
config load/parse so misconfigured aliases fail fast.
In `@docs/guides/quickstart.md`:
- Around line 68-72: The quickstart docs are out of sync with the current
interactive CLI (runSetupFormWithOverrides) which only prompts for directory,
ports, sandbox, and docker socket; update the tutorial steps (the section
covering the setup wizard currently claiming company name, LLM provider, and
template prompts) to reflect the actual prompts and wording produced by
runSetupFormWithOverrides, remove or revise the incorrect claims at the
referenced lines, and ensure the dependent claim later in the doc is updated as
well; verify the updated copy matches the CLI flow verbatim so first-run
expectations align with the actual prompts.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 700801cf-7792-4064-86fb-f53509f8e394
📒 Files selected for processing (14)
docs/getting_started.mddocs/guides/agents.mddocs/guides/budget.mddocs/guides/company-config.mddocs/guides/contributing.mddocs/guides/deployment.mddocs/guides/index.mddocs/guides/mcp-tools.mddocs/guides/memory.mddocs/guides/quickstart.mddocs/guides/security.mddocs/index.mddocs/user_guide.mdmkdocs.yml
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
🧠 Learnings (43)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
📚 Learning: 2026-03-31T14:40:41.736Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:40:41.736Z
Learning: Applies to .github/CHANGELOG.md : Changelog: `.github/CHANGELOG.md` (auto-generated, do not edit)
Applied to files:
docs/getting_started.mddocs/index.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Applied to files:
docs/getting_started.mddocs/guides/index.mddocs/guides/security.mddocs/guides/company-config.mddocs/guides/agents.mddocs/guides/contributing.mddocs/guides/deployment.mddocs/guides/quickstart.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Web dashboard: see `web/CLAUDE.md` for commands, design system, and component inventory
Applied to files:
docs/getting_started.mddocs/guides/deployment.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mddocs/index.mdmkdocs.ymldocs/guides/index.mddocs/guides/company-config.mddocs/guides/memory.mddocs/guides/agents.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
docs/getting_started.mddocs/user_guide.mddocs/index.mdmkdocs.ymldocs/guides/index.mddocs/guides/company-config.mddocs/guides/memory.mddocs/guides/agents.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Applied to files:
docs/getting_started.mddocs/user_guide.mddocs/index.mdmkdocs.ymldocs/guides/index.mddocs/guides/security.mddocs/guides/company-config.mddocs/guides/memory.mddocs/guides/agents.mddocs/guides/contributing.mddocs/guides/deployment.mddocs/guides/quickstart.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/company-config.mddocs/guides/memory.mddocs/guides/agents.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/company-config.mddocs/guides/memory.mddocs/guides/agents.md
📚 Learning: 2026-03-31T14:40:41.736Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:40:41.736Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue; `docs/design/DESIGN_SPEC.md` is a pointer file linking to 11 design pages
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.yml
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
docs/getting_started.mddocs/user_guide.mdmkdocs.ymldocs/guides/index.mddocs/guides/company-config.mddocs/guides/memory.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to docs/**/*.md : Documentation files in `docs/` (Markdown, built with Zensical, config: `mkdocs.yml`); design spec in `docs/design/` (11 pages)
Applied to files:
docs/index.mdmkdocs.ymldocs/guides/index.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to docs/design/*.md : Update the relevant `docs/design/` page when approved deviations occur to reflect the new reality
Applied to files:
docs/index.mddocs/guides/index.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/security/**/*.py : Security package (security/): SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Security: SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies: disabled/weighted/per-category/milestone), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume).
Applied to files:
docs/guides/security.mddocs/guides/company-config.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/hr/**/*.py : HR package (hr/): hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, LLM calibration, collaboration overrides, trend detection), promotion/demotion (criteria evaluation, approval strategies, model mapping)
Applied to files:
docs/guides/company-config.mddocs/guides/agents.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/memory/**/*.py : Memory package (memory/): pluggable MemoryBackend protocol, backends/ (Mem0 adapter), retrieval pipeline (ranking, RRF fusion, injection, formatting, non-inferable filtering), shared org memory (org/), consolidation/archival (density-aware: DensityClassifier, AbstractiveSummarizer, ExtractivePreserver, DualModeConsolidationStrategy)
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/memory/**/*.py : Use MemoryBackend protocol with pluggable backends (Mem0 adapter available at backends/mem0/) for persistent agent memory
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-18T08:23:08.912Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-18T08:23:08.912Z
Learning: When approved deviations occur, update the relevant `docs/design/` page to reflect the new reality.
Applied to files:
docs/guides/memory.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget package (budget/): cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError)
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget tracking includes pre-flight/in-flight checks, auto-downgrade, billing periods, cost tiers, quota/subscription. CFO includes anomaly detection, efficiency analysis, downgrade recommendations.
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Budget: Cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError).
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/hr/**/*.py : HR engine must provide: hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, trend detection), promotion/demotion
Applied to files:
docs/guides/agents.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Applied to files:
docs/guides/agents.md
📚 Learning: 2026-03-20T08:28:32.845Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-20T08:28:32.845Z
Learning: Applies to src/synthorg/templates/**/*.py : Templates: pre-built company templates, personality presets, and builder.
Applied to files:
docs/guides/agents.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: GPG/SSH signed commits required on `main` via branch protection — all commits must be signed
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:40:41.736Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:40:41.736Z
Learning: Signed commits: required on `main` via branch protection -- all commits must be GPG/SSH signed
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-15T12:00:18.113Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T12:00:18.113Z
Learning: Commits: <type>: <description> — types: feat, fix, refactor, docs, test, chore, perf, ci. Enforced by commitizen (commit-msg hook). Signed commits: required on main via branch protection — all commits must be GPG/SSH signed.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:40:41.736Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:40:41.736Z
Learning: Applies to .github/cla-signatures.json : CLA: `cla.yml` -- contributor-assistant check on PRs, signatures in `.github/cla-signatures.json`
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to .github/cla-signatures.json : CLA check on PRs via contributor-assistant; signatures in `.github/cla-signatures.json`
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/cla-signatures.json : CLA signatures stored in .github/cla-signatures.json on the cla-signatures branch (unprotected, so the action can commit directly). CLA check via contributor-assistant/github-action on pull_request_target and issue_comment. Skips Dependabot.
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Version bumping (pre-1.0): `fix:` = patch, `feat:` = patch, `feat!:` = minor, `BREAKING CHANGE` trailer = minor. Update version in `pyproject.toml` (`[tool.commitizen].version`) and `src/synthorg/__init__.py` (`__version__`)
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:40:41.736Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:40:41.736Z
Learning: Users opt into dev channel with `synthorg config set channel dev`; dev releases flow through the same Docker + CLI pipelines as stable releases
Applied to files:
docs/guides/contributing.mddocs/guides/deployment.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to src/synthorg/**/*.py : Maintain 80% minimum test coverage (enforced in CI)
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-31T14:40:41.736Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:40:41.736Z
Learning: Applies to src/synthorg/**/*.py : Docstrings: Google style, required on public classes/functions (enforced by ruff D rules)
Applied to files:
docs/guides/contributing.md
📚 Learning: 2026-03-15T18:17:43.675Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:17:43.675Z
Learning: Applies to docker/{Dockerfile*,compose.yml} : Docker: Backend uses 3-stage build (builder → setup → distroless runtime), Chainguard Python, non-root (UID 65532), CIS-hardened. Web uses nginxinc/nginx-unprivileged, Vue 3 SPA with PrimeVue + Tailwind CSS, SPA routing, API/WebSocket proxy to backend.
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-15T19:14:27.144Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T19:14:27.144Z
Learning: Applies to src/synthorg/api/**/*.py : Authentication uses JWT + API key. Approval gate integration for high-risk operations.
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-31T14:17:24.182Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:17:24.182Z
Learning: Applies to docker/**/Dockerfile* : Docker images: backend (Chainguard distroless, non-root), web (nginx-unprivileged, SPA + API proxy), sandbox (Python + Node.js, non-root)
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile.sandbox : Docker sandbox: `synthorg-sandbox` — Python 3.14 + Node.js + git, non-root (UID 10001), agent code execution sandbox
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/docker.yml : Docker workflow: builds backend + web + sandbox images, pushes to GHCR, signs with cosign. SLSA L3 provenance attestations via actions/attest-build-provenance. Scans: Trivy (CRITICAL = hard fail, HIGH = warn) + Grype (critical cutoff) + CIS Docker Benchmark v1.6.0 compliance (informational). CVE triage via .github/.trivyignore.yaml and .github/.grype.yaml. Images only pushed after scans pass. Triggers on push to main and version tags (v*).
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to Dockerfile* : Backend images must use Chainguard distroless with non-root user; web image must use nginx-unprivileged with non-root user; sandbox image must use Python + Node.js with non-root user. All Docker files in `docker/` -- Dockerfiles, compose, `.env.example`. Single root `.dockerignore`. All images build with `context: .`
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile : Docker: 3-stage build (builder → setup → distroless runtime) for backend, Chainguard Python, non-root (UID 65532), CIS-hardened
Applied to files:
docs/guides/deployment.md
🪛 LanguageTool
docs/guides/index.md
[style] ~9-~9: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1824 characters long)
Context: ...t Tutorial if you are new to SynthOrg. !!! tip "New to SynthOrg?" Start with ...
(EN_EXCESSIVE_EXCLAMATION)
docs/guides/security.md
[style] ~339-~339: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...ire output (fail-closed) | | Log only | log_only | Log findings but pass output through...
(ADVERB_REPETITION_PREMIUM)
docs/guides/budget.md
[style] ~126-~126: Using many exclamation marks might seem excessive (in this case: 9 exclamation marks for a text that’s 5284 characters long)
Context: ...es apply (always at task assignment) | !!! tip "Downgrades never happen mid-execut...
(EN_EXCESSIVE_EXCLAMATION)
docs/guides/contributing.md
[style] ~233-~233: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4213 characters long)
Context: ... MkDocs Material features: admonitions (!!! note), tabs (=== "Tab"), code blocks...
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.22.0)
docs/index.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/security.md
[warning] 43-43: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 55-55: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 81-81: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 115-115: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 149-149: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 215-215: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 299-299: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/mcp-tools.md
[warning] 36-36: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 57-57: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 141-141: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/company-config.md
[warning] 212-212: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 339-339: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 363-363: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 377-377: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
docs/guides/memory.md
[warning] 62-62: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 66-66: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 223-223: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 250-250: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 260-260: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/budget.md
[warning] 115-115: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/contributing.md
[warning] 65-65: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 100-100: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 129-129: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/guides/quickstart.md
[warning] 38-38: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 44-44: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 113-113: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 117-117: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (14)
docs/guides/contributing.md (3)
53-83: LGTM! Commit conventions and signed commits are well documented.The conventional commit format and signed commit requirement are clearly explained, with practical examples and a link to GitHub's signing guide. This addresses the past review comment effectively.
123-150: LGTM! Testing conventions accurately document the project configuration.The documented test markers, coverage threshold, parallelism requirements, and async configuration match the actual
pyproject.tomlsettings.
182-182: Guideline is correct—Python 3.14 is released and implements PEP 649.Python 3.14.3 (released Feb 2026) includes PEP 649 (deferred evaluation of annotations), so the prohibition on
from __future__ import annotationsis valid. The project's>=3.14requirement inpyproject.tomlaligns with this guideline, and the codebase complies (no such imports found).docs/getting_started.md (1)
168-168: LGTM! Contributing guide link appropriately placed in Next Steps.The cross-reference to the new Contributing guide is well-positioned for developers who have completed the initial setup.
docs/user_guide.md (1)
117-117: LGTM! Guides landing page link appropriately placed.The cross-reference to the new Guides section provides a clear next step for users after initial setup.
docs/index.md (1)
34-40: LGTM! Guides card follows existing homepage pattern.The new Guides card is consistent with the existing User Guide and Developer Setup cards, providing a clear entry point to the comprehensive guides collection.
mkdocs.yml (1)
95-105: LGTM! Guides navigation section is well-structured.The navigation hierarchy is consistent with existing sections and provides clear labels for all guide topics. The structure (landing page followed by topical guides) follows the established pattern.
docs/guides/index.md (1)
1-90: LGTM! Guides landing page provides clear navigation.The grid layout with descriptive cards and icons makes it easy for users to find the guide they need. The tip admonition directing new users to the Quickstart is helpful.
docs/guides/security.md (2)
37-149: LGTM! Trust strategies are comprehensively documented.The four trust strategies (disabled, weighted, per-category, milestone) are well-explained with clear examples. The security invariant requiring human approval for
standard_to_elevatedtransitions is consistently documented and matches the validation logic.
184-299: LGTM! Security configuration accurately documents validation constraints.The documented validation constraints (hard_deny/auto_approve overlap prohibition, bypass mode restriction) match the actual validators in
src/synthorg/security/config.py. The custom policies and rule engine sections provide clear guidance.docs/guides/mcp-tools.md (3)
99-162: LGTM! Tool filtering and caching configuration are clearly explained.The allowlist/denylist documentation with the overlap prohibition matches the validator in
MCPServerConfig. The caching behavior explanation (key-based on tool name + arguments) provides useful operational guidance.
91-91: No action needed—the constraint is correctly implemented.The
MCPServerConfigvalidator insrc/synthorg/tools/mcp/config.py(lines 79–84) includes thele=600constraint ontimeout_seconds, and the documentation accurately reflects this maximum. The original concern was based on incomplete information about the validator snippet.> Likely an incorrect or invalid review comment.
14-26: No issue—the guide's statement is correct. Server name uniqueness is enforced via the_validate_unique_server_namesvalidator insrc/synthorg/tools/mcp/config.py(line 165), which validates during configuration parsing using Pydantic's@model_validatordecorator.docs/guides/memory.md (1)
109-111: Please verify documented memory config options againstMemoryConfig/MemoryRetrievalConfig.These sections may drift from runtime validation (storage backends, consolidation interval options, and retrieval fields). Please confirm the docs match the current schema before merge.
#!/bin/bash # Verify actual memory config schema/validators against docs claims. set -euo pipefail fd -p "config.py" src/synthorg/memory echo "=== Storage allowed values ===" rg -n -C3 "_VALID_VECTOR_STORES|_VALID_HISTORY_STORES|vector_store|history_store" src/synthorg/memory/config.py echo echo "=== Consolidation interval options ===" rg -n -C3 "consolidation_interval|ConsolidationInterval|Literal\\[" src/synthorg/memory/config.py echo echo "=== Retrieval config fields and constraints ===" rg -n -C4 "class MemoryRetrievalConfig|relevance_weight|recency_weight|fusion_strategy|rrf_k|model_validator|field_validator" src/synthorg/memory/config.pyAlso applies to: 125-125, 136-151
| - No self-downgrades (e.g. `["large", "large"]` is rejected) | ||
| - No duplicate source aliases (each source can only appear once) | ||
| - Aliases must reference models defined in your `providers` configuration | ||
|
|
There was a problem hiding this comment.
Documented downgrade alias validation is not implemented.
Line 145 states alias references are validated against configured providers, but AutoDowngradeConfig validation (in src/synthorg/budget/config.py) only enforces no self-downgrades and no duplicate sources. This will mislead users into expecting config-load failures that do not currently occur.
📝 Proposed doc fix
**Validation rules:**
- No self-downgrades (e.g. `["large", "large"]` is rejected)
- No duplicate source aliases (each source can only appear once)
-- Aliases must reference models defined in your `providers` configuration
+- Ensure aliases in `downgrade_map` also exist in your provider model aliases/IDs (recommended validation at org config level)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - No self-downgrades (e.g. `["large", "large"]` is rejected) | |
| - No duplicate source aliases (each source can only appear once) | |
| - Aliases must reference models defined in your `providers` configuration | |
| - No self-downgrades (e.g. `["large", "large"]` is rejected) | |
| - No duplicate source aliases (each source can only appear once) | |
| - Ensure aliases in `downgrade_map` also exist in your provider model aliases/IDs (recommended validation at org config level) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/budget.md` around lines 143 - 146, The docs claim alias targets
are validated against the configured providers but the AutoDowngradeConfig class
lacks that check; update AutoDowngradeConfig (in src/synthorg/budget/config.py)
to validate that every alias target referenced in its aliases exists in the
providers configuration (e.g., by adding a pydantic root_validator or explicit
validate() method that receives the providers dict), and raise a clear
validation error when an alias references a model not present in providers;
ensure this validation runs during config load/parse so misconfigured aliases
fail fast.
…teps - budget.md: soften alias validation claim -- AutoDowngradeConfig does not cross-validate aliases against providers at config load time - quickstart.md: fix wizard steps to match actual CLI prompts (directory, ports, sandbox) and move company config (name, provider, template) to the web dashboard setup wizard section where it actually happens Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/guides/budget.md`:
- Line 95: The doc currently ties `critical_at` to auto-downgrade semantics but
the downgrade is actually governed by the separate field
`budget.auto_downgrade.threshold`; update the line that reads "`critical_at`
reached | Critical alert, auto-downgrade triggers (if enabled)" to clearly
decouple them by stating that `critical_at` only marks a critical alert while
auto-downgrade activation is controlled by `budget.auto_downgrade.threshold`,
and add a short note referencing both `critical_at` (alert marker) and
`budget.auto_downgrade.threshold` (downgrade trigger) so operators are not
misled.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1d65deb8-5e0c-4df6-9535-346f0f39dff0
📒 Files selected for processing (2)
docs/guides/budget.mddocs/guides/quickstart.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
📚 Learning: 2026-03-26T15:18:16.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-26T15:18:16.848Z
Learning: Applies to src/synthorg/api/**/*.py : Litestar API must include setup wizard, auth/, auto-wiring, and lifecycle management
Applied to files:
docs/guides/quickstart.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Applied to files:
docs/guides/quickstart.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget package (budget/): cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError)
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget tracking includes pre-flight/in-flight checks, auto-downgrade, billing periods, cost tiers, quota/subscription. CFO includes anomaly detection, efficiency analysis, downgrade recommendations.
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Budget: Cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError).
Applied to files:
docs/guides/budget.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Applies to src/synthorg/**/*.py : Use Pydantic v2 conventions: `BaseModel`, `model_validator`, `computed_field`, `ConfigDict`. For derived values use `computed_field` instead of storing + validating redundant fields. Use `NotBlankStr` (from `core.types`) for all identifier/name fields — including optional (`NotBlankStr | None`) and tuple (`tuple[NotBlankStr, ...]`) variants — instead of manual whitespace validators.
Applied to files:
docs/guides/budget.md
🪛 LanguageTool
docs/guides/budget.md
[style] ~126-~126: Using many exclamation marks might seem excessive (in this case: 9 exclamation marks for a text that’s 5355 characters long)
Context: ...es apply (always at task assignment) | !!! tip "Downgrades never happen mid-execut...
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.22.0)
docs/guides/budget.md
[warning] 65-65: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 100-100: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 129-129: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (16)
docs/guides/budget.md (1)
143-146: Good correction on downgrade alias validation expectations.This wording now matches current behavior: config-time checks cover map shape/consistency, while provider-alias resolvability is not enforced at load time.
docs/guides/quickstart.md (15)
1-8: LGTM! Clear and well-structured introduction.The front matter and opening paragraph effectively set expectations for the tutorial scope and duration.
12-24: LGTM! Effective visual introduction to the template.The Mermaid diagram and role descriptions provide a clear mental model of what users will create.
27-30: LGTM! Prerequisites are clear and appropriate.The requirements are well-defined with helpful external links.
58-74: LGTM! The CLI wizard description correctly separates infrastructure setup from company configuration.The updated content properly distinguishes between the CLI
initwizard (infrastructure settings) and the dashboard setup wizard (company config). This addresses the previous concern about wizard steps being out of sync. The secret generation claim is also validated by the context snippets confirming these environment variables are required and generated bysynthorg init.
95-110: LGTM! Dashboard setup flow is clear and accurate.The localhost:3000 URL matches the default WEB_PORT from docker/compose.yml, and the dashboard setup wizard description correctly covers company configuration (name, provider, template), properly separated from the CLI infrastructure setup.
135-162: LGTM! Excellent explanation of the task processing pipeline.The Mermaid sequence diagram effectively illustrates the end-to-end flow, and the accompanying text provides clear context for each step. The ReAct loop reference is technically accurate and helps users understand the agent execution model.
50-52: Thesynthorg versioncommand is properly implemented in the CLI.Verification confirms that
cli/cmd/version.godefines the version command as a Cobra command and it is correctly registered with the root command, making it available for users as documented in the quickstart guide.
54-54: The referenced file exists at the expected location (docs/user_guide.md), so there is no broken link issue. No action needed.> Likely an incorrect or invalid review comment.
174-174: Docker volume name is accurate.The documentation correctly states that data persists in the
synthorg-datavolume, which is confirmed in the docker-compose configuration.
131-131: The REST API reference path is correct—docs/rest-api.mdexists and is properly referenced.
45-45: No action required. The Windows installation script URLhttps://synthorg.io/get/install.ps1is accessible and serving content correctly (HTTP 200, content-type: application/octet-stream, 4999 bytes).
69-69: Backend API port default is correctly documented as 3001. The configuration across docker/.env.example and docker/compose.yml confirms this default is accurately reflected in the quickstart guide.
39-39: The installation script URL is accessible and functioning correctly.
180-183: Verify that all referenced guide files exist.Confirm that the linked guide files (
company-config.md,agents.md,budget.md,deployment.md) exist in thedocs/guides/directory as these should be part of the same PR.#!/bin/bash # Check if all referenced guide files exist fd -t f '^(company-config|agents|budget|deployment)\.md$' docs/guides/
83-83: Implementation confirmed and correctly documented. The deployment guide contains an "Image Verification" section, and the CLI implements cosign signature verification duringsynthorg startvia the verify package (supporting both v3 and v2 formats). Users can bypass verification with--skip-verifyif needed.
…et guide critical_at is purely an alert marker. Auto-downgrade is governed by the separate auto_downgrade.threshold field (default 85%), checked independently in the budget enforcer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
🤖 I have created a release *beep* *boop* --- ## [0.5.4](v0.5.3...v0.5.4) (2026-04-01) ### Features * artifact and project management UI in web dashboard ([#954](#954)) ([00a0430](00a0430)) * embed MkDocs build output in React web dashboard at /docs ([#948](#948)) ([f229fc2](f229fc2)) * personality preset discovery API and user-defined preset CRUD ([#952](#952)) ([497848a](497848a)) * support multi-provider model resolution with budget-based selection ([#953](#953)) ([146b782](146b782)) * support per-agent memory retention overrides ([#209](#209)) ([#951](#951)) ([020c610](020c610)) ### Documentation * write user guides and tutorials ([#949](#949)) ([1367225](1367225)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Summary
docs/guides/(2,817 lines total) covering the full user journey from quickstart to production deploymentmkdocs.ymlnav with new Guides section (10 entries)docs/index.md,docs/user_guide.md, anddocs/getting_started.mdGuides written
Test plan
uv run zensical buildexits 0 (pre-existing mkdocstrings errors unrelated to guides)mkdocs.ymlnav validates correctly (10 guide entries in Guides section)docs/guides/uv run zensical serve-- verify Guides tab renders, grid cards link correctly, Mermaid diagrams display, tabbed content worksCloses #293
🤖 Generated with Claude Code