Question 1

Why does Archon docs llms.txt return 404 and how to fix it?

Accepted Answer

The Archon docs website uses Starlight, which does not include llms.txt by default. To resolve the 404 and provide AI-friendly endpoints, add the starlight-llms-txt plugin: 
1. In packages/docs-web, run `npm install -D starlight-llms-txt`
2. In astro.config.mjs, import the plugin and add it to the starlight() plugins array:
   ```js
   import starlightLlmsTxt from 'starlight-llms-txt';
   // inside starlight config
   plugins: [starlightLlmsTxt()],
   ```
3. Rebuild and deploy.
After deployment, `/llms.txt`, `/llms-full.txt`, and `/llms-small.txt` will serve the documentation content for AI tools.

Question 2

Why is my Codex node's structured output undefined or silently lost when using output_format?

Accepted Answer

This is a known bug where the Codex provider concatenates multiple agent_message items into invalid JSON. Upgrade to the latest Archon version that includes the fix from PR #1859. The provider now uses only the last agent_message for structured output parsing. If upgrading is not possible, a temporary workaround is to avoid output_format or prompt the model to emit a single JSON response.

Question 3

Why does Archon say 'Command prompt not found' for a symlinked command file in .archon/commands?

Accepted Answer

Prior versions of Archon used Dirent.isFile() which does not recognize symbolic links, causing custom command .md files to be silently ignored. Upgrade Archon to include the fix from PR #1857, which makes command discovery follow symlinks. As a temporary workaround, copy the command file into the target directory instead of symlinking.

Question 4

Why does my DAG workflow node with output_format fail on Codex with 'additionalProperties is required to be supplied and to be false' error?

Accepted Answer

This happens because the Codex provider forwards the output_format schema directly to OpenAI's Structured Outputs API, which requires every object to have `additionalProperties: false`. OpenAI rejects schemas missing this property. To fix, manually add `additionalProperties: false` to all objects in your workflow YAML's output_format. For example, change:
```yaml
output_format:
  type: object
  properties:
    issue_type: { type: string, enum: [bug, feature, enhancement] }
    title: { type: string }
  required: [issue_type, title]
```
to:
```yaml
output_format:
  type: object
  additionalProperties: false
  properties:
    issue_type: { type: string, enum: [bug, feature, enhancement] }
    title: { type: string }
  required: [issue_type, title]
```
For bundled workflows like `archon-fix-github-issue`, you may need to override the workflow definition or add the missing property directly in your copy. This is a known issue (#1843) with the Codex provider; a permanent fix to auto-normalize schemas is expected in a future release. Until then, always include `additionalProperties: false` on every object in your output_format schemas when using Codex.

Question 5

After upgrading Archon, why do I get 'column user_id does not exist' errors and how to fix it?

Accepted Answer

Archon versions before v0.4.2 did not auto-apply Postgres schema changes on startup, causing missing columns after upgrades. Upgrade to v0.4.2 or later, where the Postgres adapter now runs the idempotent migration SQL on every boot, just like SQLite. No manual psql steps are needed. If you cannot upgrade immediately, you can temporarily run migrations/000_combined.sql against your database manually.

Archon

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects