NimsForest Issue Runbook

Overview

NimsForest Issue is an issue tracking service for the NimsForest ecosystem. It provides a public web form for reporting issues, an API for programmatic access, and an admin dashboard for triage and management.

Infrastructure

Server: issues.nimsforest.nimsforest.com
Host: land (46.225.164.179), Docker container, port 8085
Image: registry.nimsforest.com/nimsforestissue:v0.2.0
Config: /opt/nimsforestissue/config.yaml (mounted to ~/.nimsforestissue/config.yaml)
Data: /opt/nimsforestissue/data/ (mounted to /data)
NATS: nats://nimsforest.nimsforest.com:4222

Environment Variables

| Variable | Purpose | Required | |----------|---------|----------| | NATS_URL | Wind (NATS) connection for events + chat widget | Optional (events/chat disabled without it) |

Health Check

curl https://issues.nimsforest.nimsforest.com/api/v1/health

API Endpoints

| Method | Path | Auth | Description | |--------|------|------|-------------| | GET /api/v1/health | none | Health check | | POST /api/v1/issues | Bearer (api) | Create issue | | GET /api/v1/issues | Bearer (api) | List issues (query: status, category, project, active_only, stage) | | GET /api/v1/issues/{id} | Bearer (api) | Get single issue | | PATCH /api/v1/issues/{id} | Bearer (api) | Update issue | | DELETE /api/v1/issues/{id} | Bearer (api) | Delete issue | | PUT /api/v1/issues/{id}/plan | Bearer (api) | Update plan text and status | | POST /api/v1/issues/{id}/comments | Bearer (api) | Add comment | | POST /api/v1/issues/{id}/nim-actions | Bearer (api) | Record agent action | | GET /api/v1/stats | Bearer (api) | Aggregate statistics | | GET /api/v1/reports/quality | Bearer (api) | Quality review report | | GET /api/v1/runbook | none | This runbook (markdown) |

Issue Lifecycle

Status

| Status | Meaning | Set by | |--------|---------|--------| | open | New issue, not yet groomed | Issue creation | | groomed | Triaged and ready for planning | groom-issues skill | | planning | Agent is writing an implementation plan | plan-issues skill | | proposed | Plan submitted for human review | plan-issues skill | | accepted | Plan approved, ready for implementation | Human via UI | | rejected | Plan rejected | Human via UI | | implementing | Agent is actively implementing the plan | next-plan skill | | done | Implementation is complete | next-plan skill | | closed | Issue closed manually | Human via UI |

Stage (shorthand filter)

| Stage | Resolves to | Used by | |-------|------------|---------| | groomable | open | groom-issues | | plannable | groomed | plan-issues | | implementable | accepted | next-plan | | active | all except done, closed | dashboards |

Wind Events

Issue events are published to Wind (NATS) as leaves:

issue.created — new issue filed
issue.updated — status/priority/plan changed
issue.commented — comment added

Chat Widget

Embeddable nim chat on admin issue detail pages. Uses github.com/nimsforest/nimschatwidget package.

Requirements

NATS connected (Wind)
Forest pipeline running (river → tree → nim → agentclaudecode)

How it works

Admin opens /admin/issues/{id} → floating green chat button appears (bottom-right)
User clicks button → slide panel with nim selector dropdown
User sends message → Source publishes to river.chat.widget via JetStream
Forest tree (message-chat) watches river.chat.>, routes to target nim with reply_subject=song.nimschatwidget.{sessionID}
Nim responds via agentclaudecode → response published to song.nimschatwidget.{sessionID}
Songbird catches response → delivers via SSE → appears in chat panel

Standalone service

nimschatwidget also runs as a standalone container on land at chatwidget.nimsforest.com (:8096). Other services can embed the widget via script tag without importing the Go package:

<script>
window.nimschatwidgetConfig = {
    baseURL: 'https://chatwidget.nimsforest.com',
    sessionId: 'unique-session-id',
    context: 'context for the nim',
    defaultNim: 'nimble'
};
</script>
<script src="https://chatwidget.nimsforest.com/widget"></script>

Endpoints (behind admin auth at /admin/chat/)

| Method | Path | Description | |--------|------|-------------| | POST /admin/chat/send | Send message to nim | | GET /admin/chat/nims | List available nims | | GET /admin/chat/events?session={id} | SSE stream for responses | | GET /admin/chat/widget | Serve widget JS |

Troubleshooting

Chat button not visible: Check that NATS is connected. Verify logs show "Chat widget enabled (publishing to river.chat.widget)".

"Nim is thinking..." never resolves: Check agentclaudecode logs on land. Most common cause: expired Claude API credentials. Fix: copy fresh ~/.claude/.credentials.json from neoremote to /opt/agentclaudecode/credentials.json on land and restart the container.

Response not arriving: If response goes to song.webchat.* instead of song.nimschatwidget.*, the message.lua tree script needs updating. The tree must respect reply_subject from the incoming message.

Authentication

Two separate tokens configured in config.yaml:

admin_token: Used for web dashboard login (session cookie)
api_token: Used as Bearer token for API access

HydraBooks