Coding Conventions

Analysis Date: 2026-04-17

Project Nature

OhnePapier is a Docker Compose orchestration project — there is no application source code. Conventions apply to configuration files, documentation, naming, and philosophical/ethical framing. All user-facing documentation is written in German. Internal operational files (CLAUDE.md, .gitignore) are in English.

Configuration Style

docker-compose.yml:
- Services use concise lowercase names: broker, db, webserver, paperless-ai
- All services include restart: unless-stopped
- Volumes are declared at the bottom under a top-level volumes: block, using short names: data, media, pgdata, redisdata, paperless-ai_data
- Port mappings use the "HOST:CONTAINER" string form: "8000:8000"
- Environment variables with fallbacks use shell default syntax: ${PAPERLESS_AI_PORT:-3000}
- Security-sensitive services use cap_drop: [ALL] and security_opt: [no-new-privileges=true] (see paperless-ai service)
- Secrets and credentials live in docker-compose.env (env_file), never inline in the compose file
- The docker-compose.env file is gitignored — it must be created manually on each install

Environment variable conventions:
- PAPERLESS_API_URL always ends with /api
- PAPERLESS_URL never ends with /api
- Ollama host access uses host.docker.internal:11434 (not localhost) because Ollama runs on the host, not inside Docker
- SCAN_INTERVAL uses cron syntax: */30 * * * *

File: docker-compose.yml — the single source of truth for the stack.
File: docker-compose.env — gitignored secrets (ADMIN_USER, ADMIN_PASSWORD, SECRET_KEY, etc.)
File: .env — non-secret defaults (e.g. PAPERLESS_AI_PORT)

Naming Conventions

Services:
- Lowercase with hyphens: paperless-ai, webserver, broker, db
- Service names double as internal DNS hostnames (e.g. http://webserver:8000)

Volumes:
- Lowercase, no hyphens preferred for core volumes: data, media, pgdata, redisdata
- Service-scoped volumes use underscore: paperless-ai_data

Files:
- Documentation files use ALL_CAPS with underscores: CLAUDE.md, NO_AHAB_GUIDE.md, README.md
- License files: LICENSE.md, CKL.md, HHL.md
- Manifests use sequential numbering: manifest_59_...md, manifest_60_...md

Ports:
- Paperless-ngx web UI: :8000
- paperless-ai: :3000
- PostgreSQL: :5432
- Redis: :6379
- Ollama (host): :11434

Documentation Style

README.md is written in German and uses:
- Emoji as visual anchors (sparingly: 🌲, 🍪, 📄, 🔍, 🦙, 🏷️, 🧩)
- ASCII box diagrams for architecture (┌─, │, └─, ▼, ►)
- Code blocks for bash commands and env config
- Tables for configuration notes (two-column: Thema / Detail)
- Checkboxes for project status: - [x] done, - [ ] pending
- Prose in the first person plural / community voice ("Der Crumbforest wächst...")

CLAUDE.md is in English and serves as the operational handoff to AI agents. It contains:
- Stack reference table
- Bash commands for common operations
- Data flow diagram (ASCII art)
- Pre-flight checklist (numbered, bold labels)
- Configuration block with inline comments
- Project status with emoji checkboxes
- Philosophical context section

Manifests (manifest_NN_title.md) are philosophical/narrative documents. They use:
- Roman-numeral section headings (I, II, III...)
- Prose poetry style
- JSON metadata block at the end under "Crumbnotiz · Baumrinde"
- A closing "Krümeleule" section (owl voice, short poetic reflection)
- Consistent header: CrumbCrew · OZM · Nullfeld · [Month Year]

Crumbforest Philosophical Principles

All changes to this project must be evaluated against Crumbforest principles. These are not optional — they define what is acceptable work in this codebase.

NO_AHAB_GUIDE.md — Anti-Obsession Protocol

File: NO_AHAB_GUIDE.md

Three warning signs that work has become Ahab-like (stop and reconsider):
1. Druck — "Ich MUSS das fertig bekommen" (pressure to finish)
2. Vergleich — "Ist meine Kunst gut genug?" (comparison)
3. Zwang — "Ich muss zeigen, dass ich's kann" (compulsion to prove)

The prescribed response to any of these: Nullfeld betreten (enter the null field — pause and reset).

Anti-Ahab principles for technical work:
- Kunst ist Frage, kein Beweis — work as inquiry, not proof
- Kunst ist Präsenz, kein Ziel — presence over outcome
- Kunst ist Resonanz, kein Score — resonance over metrics

Permitted states:
- Unvollständig (incomplete) is acceptable
- Chaotisch (chaotic) is acceptable
- Abbrechen (stopping) is acceptable

Prohibited states: Deadlines as drivers, comparison as motivation, market/perfection as goals.

When suggesting changes: prefer simple and maintainable over clever and optimal. Never force a solution. If a workaround feels like hunting, it probably is.

CKL — Crumbforest Kernel License

File: CKL.md

Ethical license extending MIT (non-binding, voluntary). Key constraints for any extension or fork:

Non-military: No use in military applications, autonomous weapons, or surveillance systems
Non-manipulative: No systems generating hate, manipulation, or psychological harm
Community-oriented: Attribution when possible; changes documented transparently; help others understand the system
Mensch vor Maschine (Human before Machine): Systems must respect human decisions, operate transparently, and not enforce dependencies
Nature and children: Systems must strengthen, not exploit

HHL — Haltung-und-Herz-Lizenz (Attitude and Heart License)

File: HHL.md

Seven promises (poetic, non-binding):
1. Use the kernel in a way you'd proudly show to a child
2. Write code that comes back like a boomerang (reversible, no lock-in)
3. Build systems that give more than they take
4. Remember every bit leaves a footprint
5. Let no machine decide what a human is allowed to feel
6. If you want to destroy something, destroy bugs — not people
7. The forest is older than you. Be kind.

Practical Application of Principles

When modifying docker-compose.yml:
- Do not add cloud dependencies or external telemetry
- Do not add surveillance or tracking services
- Prefer named volumes over bind mounts for portability
- Prefer the simplest working configuration over the most optimized

When writing documentation:
- Write in German for user-facing docs
- Use the whale/forest/crumb metaphors when introducing new concepts
- New manifests follow the sequential numbering pattern (manifest_NN_title.md)

Gitignore Conventions

Gitignored by design (never commit):
- docker-compose.env — credentials (ADMIN_USER, ADMIN_PASSWORD, SECRET_KEY)
- *.token, *.key, pbkdf2_* — all secrets and derived keys
- consume/, export/ — local Docker volume mount folders
- .DS_Store — macOS metadata

Change Philosophy

From CLAUDE.md and manifests: prefer simple and maintainable over clever and optimal. The project grows like a spiral (Spirale), not like a tower (Turm). Each addition should deepen relationships between components, not add complexity for its own sake.

The Ishmael principle (from Manifest #60): Ahab will beweisen. Ishmael will verstehen. Observe and understand before optimizing. Avoid reducing the system to a single metric.

Convention analysis: 2026-04-17