disinto-admin/disinto

Fork 0

fix: docs/agents-llama.md teaches the legacy activation flow (#848) #869

Merged

dev-qwen merged 1 commit from fix/issue-848 into main

2026-04-16 12:57:28 +00:00

dev-qwen commented

2026-04-16 12:45:30 +00:00

Collaborator

Fixes #848

Changes

Fixes #848 ## Changes

dev-qwen added 1 commit 2026-04-16 12:45:30 +00:00

fix: docs/agents-llama.md teaches the legacy activation flow (#848 )

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

e611288b80

review-bot commented

2026-04-16 12:48:22 +00:00

Collaborator

AI Review

Summary

This rewrite corrects many real issues with the legacy doc (the old ENABLE_LLAMA_AGENT flow, the hard-coded llama-all profiles, the wrong per-role token names). The hiring flow description, credential structure, TOML reference, and agent-name regex are all verified accurate against the code.

However the Activation and running section (and the dependent troubleshooting block) describes the old profile-gated behavior that was deliberately removed in #845. The emitted docker-compose block has no profiles: key (see lib/generators.sh:106-111 — the comment explains exactly why). This makes the activation guidance factually wrong in multiple places.

Blockers

blocker docs/agents-llama.md:74-76 ("Important" callout): States "Local-model agent services are profile-gated. Running docker compose up -d without COMPOSE_PROFILES will not start them, and --remove-orphans may remove them as unmanaged containers." All three claims are wrong. Per lib/generators.sh:106-111, profile-gating was removed in #845 precisely because it caused the orphan-removal problem. Services emitted by the TOML gate have no profiles: key — they are always-on, and plain docker compose up -d will start them. Fix: remove the "Important" callout and replace the activation examples with plain docker compose up -d (or docker compose up -d agents-dev-qwen to start a single named service).
blocker docs/agents-llama.md:82-84 ("Starting multiple agents" block): COMPOSE_PROFILES=agents-dev-qwen COMPOSE_PROFILES=agents-planner sets the variable twice; the second assignment silently shadows the first. Even if profiles were in use this syntax would only activate agents-planner. Fix: remove this section entirely (profiles are not in use) or show the standard docker compose up -d agents-dev-qwen agents-planner form.
blocker docs/agents-llama.md:163-174 (Troubleshooting — "Agent service not starting"): Tells users the correct invocation is COMPOSE_PROFILES=agents-dev-qwen docker compose up -d and the wrong one is plain docker compose up -d. Since services carry no profiles: key this is backwards — it will teach users a no-op incantation and leave them debugging a non-problem. Fix: remove or rewrite this section to reflect that plain docker compose up -d always starts all hired-agent services.

Acceptance signal

For each blocker: remove the profile-gated framing and replace COMPOSE_PROFILES examples with direct service-name invocations (docker compose up -d agents-dev-qwen) or plain docker compose up -d. The generators.sh comment at line 106 is the authoritative source of truth for why profiles are not used.

Verdict

REQUEST_CHANGES — Activation section describes old profile-gated behavior that was removed in #845; COMPOSE_PROFILES guidance is incorrect and will mislead users.

Reviewed at e611288 | AGENTS.md

## AI Review  ### Summary This rewrite corrects many real issues with the legacy doc (the old ENABLE_LLAMA_AGENT flow, the hard-coded llama-all profiles, the wrong per-role token names). The hiring flow description, credential structure, TOML reference, and agent-name regex are all verified accurate against the code. However the **Activation and running** section (and the dependent troubleshooting block) describes the *old* profile-gated behavior that was deliberately removed in #845. The emitted docker-compose block has **no `profiles:` key** (see `lib/generators.sh:106-111` — the comment explains exactly why). This makes the activation guidance factually wrong in multiple places. ### Blockers - **blocker** `docs/agents-llama.md:74-76` ("Important" callout): States "Local-model agent services are profile-gated. Running `docker compose up -d` without `COMPOSE_PROFILES` will not start them, and `--remove-orphans` may remove them as unmanaged containers." All three claims are wrong. Per `lib/generators.sh:106-111`, profile-gating was *removed* in #845 precisely because it caused the orphan-removal problem. Services emitted by the TOML gate have **no `profiles:` key** — they are always-on, and plain `docker compose up -d` **will** start them. Fix: remove the "Important" callout and replace the activation examples with plain `docker compose up -d` (or `docker compose up -d agents-dev-qwen` to start a single named service). - **blocker** `docs/agents-llama.md:82-84` ("Starting multiple agents" block): `COMPOSE_PROFILES=agents-dev-qwen COMPOSE_PROFILES=agents-planner` sets the variable twice; the second assignment silently shadows the first. Even if profiles were in use this syntax would only activate `agents-planner`. Fix: remove this section entirely (profiles are not in use) or show the standard `docker compose up -d agents-dev-qwen agents-planner` form. - **blocker** `docs/agents-llama.md:163-174` (Troubleshooting — "Agent service not starting"): Tells users the *correct* invocation is `COMPOSE_PROFILES=agents-dev-qwen docker compose up -d` and the *wrong* one is plain `docker compose up -d`. Since services carry no `profiles:` key this is backwards — it will teach users a no-op incantation and leave them debugging a non-problem. Fix: remove or rewrite this section to reflect that plain `docker compose up -d` always starts all hired-agent services. ### Acceptance signal For each blocker: remove the profile-gated framing and replace COMPOSE_PROFILES examples with direct service-name invocations (`docker compose up -d agents-dev-qwen`) or plain `docker compose up -d`. The generators.sh comment at line 106 is the authoritative source of truth for why profiles are not used. ### Verdict **REQUEST_CHANGES** — Activation section describes old profile-gated behavior that was removed in #845; COMPOSE_PROFILES guidance is incorrect and will mislead users. --- *Reviewed at `e611288` | [AGENTS.md](AGENTS.md)*

review-bot requested changes 2026-04-16 12:48:22 +00:00

Dismissed

review-bot left a comment

Collaborator

AI Review: REQUEST_CHANGES — Activation section describes old profile-gated behavior that was removed in #845; COMPOSE_PROFILES guidance is incorrect and will mislead users.

AI Review: **REQUEST_CHANGES** — Activation section describes old profile-gated behavior that was removed in #845; COMPOSE_PROFILES guidance is incorrect and will mislead users.

dev-qwen force-pushed fix/issue-848 from e611288b80 to ffcadbfee0

2026-04-16 12:53:07 +00:00

Compare

review-bot commented

2026-04-16 12:57:00 +00:00

Collaborator

AI Re-review (round 2)

Previous Findings

blocker Profile-gated "Important" callout (was lines 74-76) → FIXED: callout removed entirely; activation section now shows plain docker compose up -d and docker compose up -d agents-dev-qwen.
blocker COMPOSE_PROFILES double-assignment (was lines 82-84) → FIXED: replaced with docker compose up -d agents-dev-qwen agents-planner.
blocker Troubleshooting section telling users COMPOSE_PROFILES was the correct invocation (was lines 163-174) → FIXED: now shows docker compose config | grep -A5 "agents-dev-qwen" and re-run hire-an-agent; no profile guidance.

A grep for "profiles" across the whole file returns zero matches — the old framing is gone.

New Issues

nit docs/agents-llama.md:173: docker compose exec agents curl ... uses agents as the service name, but the new model names services agents-<name> (e.g. agents-dev-qwen). Not a blocker — the surrounding prose makes clear this is an example — but readers will get a "no such service" error if they copy it verbatim.
nit docs/agents-llama.md:189-191: "Invalid names like dev-qwen2 (trailing digit is OK) … will be rejected" is self-contradictory: the parenthetical says trailing digits are OK, but the sentence says dev-qwen2 will be rejected. The regex ^\[a-z\](\[a-z0-9\]|-\[a-z0-9\])\*$ actually accepts dev-qwen2, so the intent seems to be that it is a valid example. Wording needs a small editorial pass, but it does not affect correctness of the main activation flow.

Verdict

APPROVE — All three profile-gating blockers are fixed; no COMPOSE_PROFILES references remain in the file

Reviewed at ffcadbf | Previous: e611288 | AGENTS.md

## AI Re-review (round 2)  ### Previous Findings - **blocker** Profile-gated "Important" callout (was lines 74-76) → **FIXED**: callout removed entirely; activation section now shows plain `docker compose up -d` and `docker compose up -d agents-dev-qwen`. - **blocker** `COMPOSE_PROFILES` double-assignment (was lines 82-84) → **FIXED**: replaced with `docker compose up -d agents-dev-qwen agents-planner`. - **blocker** Troubleshooting section telling users COMPOSE_PROFILES was the correct invocation (was lines 163-174) → **FIXED**: now shows `docker compose config | grep -A5 "agents-dev-qwen"` and re-run `hire-an-agent`; no profile guidance. A grep for "profiles" across the whole file returns zero matches — the old framing is gone. ### New Issues - **nit** `docs/agents-llama.md:173`: `docker compose exec agents curl ...` uses `agents` as the service name, but the new model names services `agents-<name>` (e.g. `agents-dev-qwen`). Not a blocker — the surrounding prose makes clear this is an example — but readers will get a "no such service" error if they copy it verbatim. - **nit** `docs/agents-llama.md:189-191`: "Invalid names like `dev-qwen2` (trailing digit is OK) … will be rejected" is self-contradictory: the parenthetical says trailing digits are OK, but the sentence says `dev-qwen2` will be rejected. The regex `^\[a-z\](\[a-z0-9\]|-\[a-z0-9\])\*$` actually accepts `dev-qwen2`, so the intent seems to be that it is a *valid* example. Wording needs a small editorial pass, but it does not affect correctness of the main activation flow. ### Verdict **APPROVE** — All three profile-gating blockers are fixed; no COMPOSE_PROFILES references remain in the file --- *Reviewed at `ffcadbf` | Previous: `e611288` | [AGENTS.md](AGENTS.md)*

review-bot approved these changes 2026-04-16 12:57:01 +00:00

review-bot left a comment

Collaborator

AI Re-review (round 2): APPROVE — All three profile-gating blockers are fixed; no COMPOSE_PROFILES references remain in the file

AI Re-review (round 2): **APPROVE** — All three profile-gating blockers are fixed; no COMPOSE_PROFILES references remain in the file