peter/daybook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
daybook/CLAUDE.md
peter 4a5ea8944b Add generic deployment docs and fix stale references 
Adds docs/deployment.md, a platform-agnostic guide (any Linux host with
Docker) built around a git-pull based fast-redeploy workflow, replacing the
Proxmox-specific deploy/proxmox_llm_deploy.md which was also stale (old
`persona` field, single-shared-token model predating multi-user auth).

Also: drops the unused DAYBOOK_API_TOKEN from deploy/env.example, documents
the new DELETE endpoint and capabilities `methods` field in docs/api.md and
docs/agent_quickstart.md, and fixes CLAUDE.md's OpenCode note now that
opencode.json is untracked (machine-specific MCP config).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-01 22:14:34 +01:00

5.1 KiB
Raw Blame History

CLAUDE.md

Project

Daybook is a self-hosted, multi-user Django + Django REST Framework web app where AI agents, scripts, or people publish artifacts and each logged-in user browses their own time-ordered, label-filterable feed.

The core product principle is: agents publish content, not files. The server owns IDs, styling, storage layout, dates, and normalization into browser-native HTML, image, or PDF outputs.

Current MVP Decisions

  • Each user has a personal ingest API token (DRF Token model), viewable/regenerable from Settings → Account.
  • Require source in every artifact payload — a free-text label identifying what posted it (agent-profile, script, or person name). Ownership of the resulting artifact comes from whichever user's token authenticated the POST, not from the source value itself.
  • source and tags together form one unified label system: every artifact shows all its labels next to the title, and a single label filter/query param matches against either.
  • Require login (Django session auth) for the whole app, including the feed and API reads. Ingest (POST/PATCH) stays per-user bearer-token authenticated, since agents don't have browser sessions.
  • User accounts are created/managed via Django admin (superusers only — regular users are not staff and cannot access /admin/).
  • TagColor (label color overrides) stays global/shared across all users.
  • Use random 8-character artifact IDs.
  • Start as a plain Django project; add Docker after core ingest and viewer work.
  • Preserve original markdown as .md alongside rendered .html.

Architecture Notes

  • Planning source: planning/daybook_planning.md.
  • Django project: daybook_project/.
  • Main app: artifacts/.
  • Theme CSS: static/themes/.
  • Feed template: templates/artifacts/feed.html.
  • Settings templates: templates/artifacts/settings_*.html.
  • Stored artifact files live under artifacts_store/{source}/{YYYY-MM-DD}/.

Implementation Guidelines

  • Prefer small, direct changes over broad abstractions.
  • Keep ingest normalization server-side.
  • The viewer should only need to render HTML, image, or PDF.
  • Do not make agents responsible for styling, filenames, or storage paths.
  • Preserve existing planning decisions unless the user explicitly changes them.
  • Avoid adding backwards-compatibility code before anything has shipped.

Development And Deployment Workflow

  • Develop and test locally in this workspace by default.
  • Use the local Django commands for normal iteration: python manage.py check, python manage.py migrate, and python manage.py runserver.
  • Run the local development server on 127.0.0.1:8001. Port 8000 may be reserved or blocked on this workstation.
  • Always use this same fixed port for the dev server. Never start a second instance on a different port; if 8001 is already serving, reuse it rather than starting another.
  • All artifact-posting tools (skills/daybook-posting/scripts/daybook_post.py, scripts/seed_demo_artifacts.py, and any future posting skill) must default DAYBOOK_URL to http://127.0.0.1:8001 to match.
  • Do not deploy to the Proxmox NUC during routine code iteration.
  • Treat the NUC container as the local live/staging target. Deploy there only at explicit stable checkpoints, such as an end-of-day build.
  • Before any NUC deployment, preserve /opt/daybook/deploy/.env and /opt/daybook/deploy/data.
  • After any NUC deployment or configuration change, run the documented health checks and update the NUC ops knowledge base plus planning/daybook-container-handoff.md if takeover facts changed.

Repository Notes

  • _archive_/ exists for retired or moved project docs and experiments that should not drive current implementation decisions.
  • Current deployment/takeover details live in planning/daybook-container-handoff.md; canonical NUC infrastructure details live in the NUC ops repo.

Commands

  • Install dependencies: pip install -r requirements.txt
  • Run migrations: python manage.py migrate
  • Start dev server: python manage.py runserver 127.0.0.1:8001
  • Local app URL: http://127.0.0.1:8001/
  • Local API health check: http://127.0.0.1:8001/api/capabilities
  • Django checks: python manage.py check

API Defaults

  • MVP ingest endpoint: POST /api/artifacts
  • MVP list endpoint: GET /api/artifacts?label=&day=&kind=&q=
  • Artifact view: GET /a/{id}
  • Auth: personal per-user token from Settings → Account, Authorization: Bearer <token>. Get one by creating a superuser (python manage.py createsuperuser), logging in, and visiting Settings → Account.

Claude Code / OpenCode

This project uses CLAUDE.md for project instructions, compatible with both Claude Code and OpenCode. OpenCode is configured to load this file via a local, untracked opencode.json (it contains machine-specific MCP config, so it is not committed — recreate it locally with {"$schema": "https://opencode.ai/config.json", "instructions": ["CLAUDE.md"], "permission": "allow"} plus whatever MCP servers you want). After changing opencode.json, .opencode/, or this file, restart your AI coding assistant so the updated instructions are loaded.