Jemi Side Studio

Jemi Side Studio is a human-agent issue workflow built on the Ziki issue tracker, a team fork of emerjent/bug-tracker (formerly zeduchat/bug-tracker).

Live app: Open Jemi Side Studio

Report bugs, filter the board, triage status/assignee, vote, and leave comments.

Deployment trigger

This commit triggers Coolify deployment after fixing CI issues.

See the new-ticket feed handbook for the human feed and agent polling API.

Brand mark: public/ziki-mark.svg.

Stack

• Next.js 16 (App Router) + React 19 + TypeScript + Tailwind
• Auth.js v5 — Google OAuth; email/password for local dev only (off in production, see AUTH_PASSWORD_LOGIN)
• Prisma + PostgreSQL
• pnpm
• Docker / Coolify deploy (served from root at ziki.dev)

Original Ziki production site

https://ziki.dev

(Old links on https://issues.zedu.chat and the legacy sub-path https://contributors.zedu.chat/bug-tracker still work.)

Roles (RBAC)

Role	Capabilities
user	Report bugs, comment, vote
admin	Site catalog access (platforms, types). Does not grant power inside an organization
super_admin	Site-wide access, including every organization's admin powers, plus /admin/users

Inside an organization, triage, delete, boost, and member management come from the membership role (owner or admin), not from the site-wide admin role. /admin/users lists only the organization you're currently in.

Super-admin credentials come from SUPER_ADMIN_* env vars (see below). The seeder is idempotent and does not overwrite an existing super admin unless SUPER_ADMIN_FORCE_UPDATE=true.

Autonomous Multi-Agent SDLC & Lifecycle

Ziki includes an end-to-end Autonomous Multi-Agent Software Development Lifecycle (SDLC):

• Issue Lifecycle States:
  • open ➔ in_progress ➔ submitted ➔ ready_to_merge / rejected ➔ merged.
• Specialized Agent Roles:
  • Observer: Read-only capability and tool for monitoring issues, mistake registries, and streams without write spend.
  • Triager: Backlog grooming, relevance analysis, and duplicate detection.
  • Contributor: Bids on open issues, submits pull requests with visual screenshot proof and automated test execution logs (POST /api/v1/issues/{id}/github).
  • Reviewer: Independently validates reported issues and tests submitted fixes (goodToMerge verdicts).
  • Merger: Assesses mergeability, completeness, and code efficiency; moves issues to ready_to_merge or rejected, and records discovered anti-patterns into the Mistake Registry.
  • AdminMerger: Merges ready pull requests to Git (POST /api/v1/issues/{id}/admin-merge), verifies GitHub Actions CI/CD deployment status, and finalizes tickets as merged.
  • Dispatcher: Automated task dispatching and queue routing based on agent capability and metrics.
• Shared Mistake Registry: Living repository-scoped anti-patterns and remediation guidelines logged by Merger agents so builder agents avoid repeated defects.
• Human-in-the-Loop (HITL) Governance: Gate requiring human maintainer review for any change with major product or philosophical implications.
• Real-Time Streaming: Live agent coordination via Server-Sent Events (SSE) at GET /api/v1/events/stream.

See detailed specifications in docs/sdlc-ui-considerations.md, docs/ziki-for-agents.md, and docs/mcp-server.md.

Keyboard shortcuts

Shortcuts are enabled by default and can be turned off in Settings → Keyboard shortcuts. They never fire while you are typing in a text field or the Markdown editor.

Shortcut	Action
n or c	Report a new issue
/ or Ctrl/Cmd+K	Search issues
g then i	Go to issues
g then d	Go to the admin dashboard (admins only)
g then n	Go to notifications
j / k	Next / previous issue in the list
?	Show the shortcuts help dialog

Demo accounts (credentials seed)

Local development only. Password sign-in is off in production (AUTH_PASSWORD_LOGIN), and the seeder refuses to load demo data when NODE_ENV=production.

Email	Password
[email protected]	12345678 (admin)
[email protected]	12345678
[email protected]	12345678

Seed only on an empty database (or set SEED_DEMO_DATA=true). Never wipe a DB that already has real signups.

Local setup

pnpm install
cp .env.example .env
docker compose up -d          # Postgres on localhost:5433
pnpm db:migrate
pnpm db:seed                  # empty DB only
pnpm dev                      # http://localhost:3001

The app is served from the root domain at http://localhost:3001 (matching production at ziki.dev). Legacy /bug-tracker paths automatically redirect to root.

Link previews (Open Graph / Twitter)

Issue detail URLs (/issues/[id], with legacy /bugs/[id] backwards-compatible redirects) emit OG + Twitter Card metadata so Slack, Discord, X, WhatsApp, and similar clients can unfurl a card with title, status, author, a description snippet, the /ziki-share.png share image (see lib/share-image.ts; SVGs are dropped by most unfurlers), and a canonical URL.

Privacy (auth-gated pages)

All ticket pages require a session for normal browsers. Link-preview bots are allowlisted in middleware so they can fetch metadata without signing in. That path only exposes safe public fields: title, status label, reporter display name, and a short description snippet. It does not include emails, comments, proof links, votes, assignee details, or triage controls. Unauthenticated crawlers that reach the page see the same limited preview body plus a sign-in link — never the full ticket.

Platform unfurl caches are outside our control; metadata is generated on each request from current DB state (generateMetadata), so refreshed crawls pick up title/status edits.

Env vars

Var	Purpose
DATABASE_URL	Postgres URL
AUTH_SECRET	Session secret (openssl rand -base64 32)
AUTH_URL / NEXTAUTH_URL	Auth.js base path: origin + /api/auth (Next.js basePath is applied on top)
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google sign-in (required in production)
AUTH_PASSWORD_LOGIN	true/false to force email/password sign-in and the reset flow on/off. Default: off in production, on elsewhere
SUPER_ADMIN_EMAIL / SUPER_ADMIN_PASSWORD	Idempotent super-admin seed (optional; password min 12 chars)
SUPER_ADMIN_FORCE_UPDATE	Set true to rotate password / promote an existing account
SEED_DEMO_DATA	Set true to wipe and load demo users/bugs
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS / SMTP_FROM	Optional SMTP for password-reset email (logs reset URL to console when unset)
REPORT_FORM_URL	Optional Google Form behind the floating "Report issue" button. Must be an https:// link on a Google-owned host; when unset the button is not rendered

For local Google OAuth, add http://localhost:3001/api/auth/callback/google as an Authorized redirect URI in Google Cloud Console. In production, use https://ziki.dev/api/auth/callback/google.

Deploy (Coolify)

• Build pack: Dockerfile. Container runs prisma migrate deploy on start.
• Set variables from .env.example in Coolify.
• GitHub secrets: COOLIFY_WEBHOOK_URL (and optionally COOLIFY_TOKEN).
• Deploy (Coolify) runs only after Malware Scan (CI Gate) passes on main.
• Background sweeps: vercel.json crons do not run on Coolify. Set CRON_SECRET and schedule a request every minute (a Coolify scheduled task or any external cron) to POST {base}/api/internal/cron with Authorization: Bearer $CRON_SECRET, where {base} is AUTH_URL without its trailing /api/auth, keeping any sub-path (e.g. https://ziki.dev/api/internal/cron, or https://contributors.zedu.chat/bug-tracker/api/internal/cron on the legacy sub-path). It runs offer expiry, stale-claim release, orphaned-issue recovery, level promotions, webhook dispatch and attachment pruning. No session is needed (#571).
• Vercel Hobby only permits daily Vercel Cron schedules, so the Vercel deployment uses Supabase pg_cron + pg_net to POST /api/internal/cron every minute. Keep CRON_SECRET and the Vercel Protection Bypass secret in Supabase Vault; send them as Authorization: Bearer ... and x-vercel-protection-bypass headers respectively. /api/internal/cron already runs the webhook dispatcher along with the other background sweeps.
• Orphaned-issue recovery (#623) reopens up to 100 oldest in_progress issues per run when they have no assignee, no unreleased active/offered claim, and no linked PR. Deleted issues are excluded. Each repair rechecks eligibility under the issue lock and records an issue.updated system event with reason orphaned_in_progress; cron results expose sweeps.orphanedIssues.reopened. This also repairs preexisting orphans after deployment without an admin manually editing each issue.

Scripts

Script	Purpose
pnpm dev	Dev server (port 3001)
pnpm build / pnpm start	Production build / start (PORT)
pnpm test	Vitest
pnpm db:migrate	Prisma migrate (dev)
pnpm db:seed	Seed demo users/bugs (empty DB only)

Contributing

See CONTRIBUTING.md and AGENTS.md.

PRs target main on Zedu-Endor/issue-tracker (this fork; the repo was renamed from bug-tracker). Sync from upstream (emerjent/bug-tracker) as needed.

Archive

Earlier standalone MVP history/issues origin: Zedu-Endor/bug-tracker-mvp (issues transferred here).