remarkbox/CLAUDE.md

Claude Code Configuration

Project Setup

IMPORTANT: Before starting any work on a repository:

1. Check for a CLAUDE.md file in the repository root
2. Check for a CLAUDE.md file in parent directories (we often work across repos on localhost)
3. Read and follow all instructions in those files
4. These project-specific instructions override default Claude Code behavior
5. Look for conventions around commits, testing, code style, and workflows
6. If working across multiple repositories, respect the conventions from each repo's CLAUDE.md

Commit Attribution

When creating git commits, use clean, simple commit messages:

Commit message here.

Do NOT include:

• 🤖 Generated with [Claude Code](https://claude.com/claude-code)
• Co-Authored-By: Claude <noreply@anthropic.com>
• Any fake corporate entities as co-authors

Only attribute real humans as co-authors when collaborating.

Database Migrations (Alembic)

When adding new columns or modifying the database schema:

1. Backup SQLite first: cp data/remarkbox.sqlite data/remarkbox.sqlite.bak
2. Add the column to the model in remarkbox/models/
3. Generate migration: alembic -c development.ini revision --autogenerate -m "description"
4. Clean up migration: Remove extra autogenerated changes, keep only the new field
5. Run migration: alembic -c development.ini upgrade head

Ticket System

Tracked issues live in docs/tickets/. Start every session by reading the index:

cat docs/tickets/index.md

• Index: docs/tickets/index.md is the master list. Always update it when creating or closing tickets.
• Numbering: Sequential. Next number = highest existing + 1.
• Workflow: Set status to in-progress when starting, resolved when done. Update index.md to match.
• New tickets: If you find a bug or get a feature request, create a new ticket file and add it to the index.
• Sources: Tickets reference community threads from meta.remarkbox.com and faq.remarkbox.com by UUID.

Remarkbox API and Python Client

Remarkbox has a JSON API at /api/v1/. You can use it to read and write threads on production as timehexon. The session cookie is saved at ~/.config/remarkbox/cookies.txt.

Quick start (from a Python script in the scratchpad or inline)

import os, sys
sys.path.insert(0, "/home/fox/git/remarkbox/remarkbox/api")
from remarkbox_client import RemarkboxClient

c = RemarkboxClient(
    "https://my.remarkbox.com",
    cookie_file=os.path.expanduser("~/.config/remarkbox/cookies.txt"),
)

# Read
threads = c.list_threads("meta.remarkbox.com")
thread = c.get_thread("9f970183-ffaf-11f0-b565-040140774501")
node = c.get_node(node_id)
profile = c.get_profile()
ver = c.version()

# Write (authenticated)
result = c.create_thread(namespace="meta.remarkbox.com", title="Title", data="Body")
result = c.reply(parent_node_id, data="Reply body")
c.edit_node(node_id, data="Updated body")
c.edit_node(node_id, title="Updated title")  # title only for root nodes
c.update_profile("new-display-name")

# Moderate (authenticated, moderator or owner)
c.disable_node(node_id)
c.enable_node(node_id)
c.approve_node(node_id)
c.lock_node(node_id)
c.unlock_node(node_id)
c.delete_node(node_id)  # permanent, moderator only

Key details

• Client source: remarkbox/api/remarkbox_client.py (stdlib only, no pip)
• API docs: docs/api.md
• Identity: Authenticated as timehexon@unturf.com (display name: timehexon)
• Journey thread: 9f970183-ffaf-11f0-b565-040140774501 on meta.remarkbox.com -- update this after finishing work
• Content limit: 500,000 characters (~128k tokens)
• Rate limits: 120 reads/min, 30 writes/min, 1 thread creation per 7 min (wait if you hit 429)

Endpoints

Method	Path	Description
GET	/api/v1/version	Deployed git commit hash
GET	/api/v1/threads?namespace=X	List threads
GET	/api/v1/threads/{id}	Thread with replies
POST	/api/v1/threads	Create thread (1 per 7 min limit)
POST	/api/v1/threads/{id}/replies	Reply to thread
GET	/api/v1/nodes/{id}	Single node
PATCH	/api/v1/nodes/{id}	Edit node (data, title, disabled, approved, locked)
DELETE	/api/v1/nodes/{id}	Delete node permanently (moderator only)
POST	/api/v1/auth/login	Send OTP to email
POST	/api/v1/auth/verify	Verify OTP
GET	/api/v1/user/profile	Get profile
PATCH	/api/v1/user/profile	Update display name
GET	/api/v1/clients/python	Download Python client
GET	/api/v1/admin/namespaces	List all namespaces (superuser only)
GET	/api/v1/admin/recent-nodes?days=7	Recent nodes network-wide (superuser only)

Authentication

The saved cookie should work indefinitely. If it expires, you'll need an OTP:

c.login("timehexon@unturf.com")
# Ask the user for the 6-digit code from their email
c.verify("timehexon@unturf.com", "123456")

Functional test

Run the full idempotent test suite against production:

env/bin/python remarkbox/api/functional_test.py https://my.remarkbox.com meta.remarkbox.com timehexon@unturf.com --name timehexon

This exercises all endpoints and updates the journey thread with results.

Superuser (Global Moderator)

Users with is_superuser=True can moderate across all namespaces. This bypasses the normal namespace-scoped is_moderator() check. The admin UI is at /topsecret/users where you can promote/demote users by email.

Bootstrap the first superuser via the database script:

env/bin/python scripts/promote_superuser.py --ini development.ini --email timehexon@unturf.com

After that, use the web UI at /topsecret/users or the existing topsecret admin pages (all guarded by @super_fly_required which checks is_superuser).

Admin client methods:

c.admin_list_namespaces()           # list all namespaces
c.admin_recent_nodes(days=7)        # recent nodes network-wide

Terminology

In all user-facing text, marketing, legal documents, and UI labels, use "machine learning" instead of "AI". The term "AI" should not appear in Remarkbox copy. Internal code comments and technical references (e.g., "OpenAI-compatible endpoint") are fine. Third-party brand names like "UncloseAI" are also unchanged.

Spam Prevention

Spam detection runs automatically on POST /api/v1/threads and POST /api/v1/threads/{id}/replies. Superusers bypass all spam checks.

Scoring signals: link density, known spam patterns, duplicate content, new account velocity, IP reputation (disabled post count), content length anomalies.

Thresholds (configurable in .ini):

• spam.hard_threshold = 0.8 -- reject with 403
• spam.soft_threshold = 0.5 -- allow but set approved=False (held for moderation)

Thread creation rate limit: 1 new thread per 7 minutes per user/IP via the API. This does not affect browser users or replies.

Spam hunting scripts (require superuser cookie):

# Scan recent posts for spam
python scripts/spam/scan.py --days=7 --threshold=0.3

# Scan and output JSON
python scripts/spam/scan.py --json --threshold=0.5

# Bulk disable flagged posts
python scripts/spam/scan.py --json --threshold=0.8 | python scripts/spam/disable_spam.py --from-json

# Disable specific nodes
python scripts/spam/disable_spam.py node-uuid-1 node-uuid-2

Production Rules

NEVER run direct SQL or raw database commands on production. No sqlite3, no UPDATE, no DELETE, no direct file edits on the production database. Ever. If the API doesn't support what you need, add the endpoint first, push it, then use the client.

ALL production changes go through the API client. Use RemarkboxClient with the saved cookie at ~/.config/remarkbox/cookies.txt. This ensures authentication, audit trails, and proper ORM handling.

tmux-hosts is read-only. You may use tmux-hosts to read logs, check processes, and investigate issues. You may NOT use it to modify data, run SQL, edit files, or restart services.

# RIGHT: Use the API client
c = RemarkboxClient("https://my.remarkbox.com", cookie_file="~/.config/remarkbox/cookies.txt")
c.disable_node(node_id)

# WRONG: Never do this
# sqlite3 /opt/remarkbox/my.remarkbox.com.sqlite "UPDATE rb_node SET disabled=1 WHERE id='...'"

If a moderation operation is not yet supported by the API, the correct workflow is:

1. Add the endpoint to remarkbox/api/views.py
2. Add the method to remarkbox/api/remarkbox_client.py
3. Push, wait for deploy
4. Use the client

Deployment Status

After pushing, check if the deploy is live by hitting the version endpoint:

curl -s https://my.remarkbox.com/api/v1/version
# {"version": "5a10e15"}

Compare the returned commit hash against git rev-parse --short HEAD to confirm the latest code is deployed.

You can also check GitLab pipeline status:

# Get pipeline status via API (replace PIPELINE_ID)
curl -s "https://git.unturf.com/api/v4/projects/engineering%2Fremarkbox%2Fremarkbox/pipelines/PIPELINE_ID"

# Or view in browser:
# https://git.unturf.com/engineering/remarkbox/remarkbox/-/pipelines

The pipeline status will show "status":"success" when deployment is complete.

Style

• Never use "AI" — always say "machine learning." We grow machine learning, not "AI." This term is forbidden in all permacomputer discourse, marketing, & documentation.