# AGENTS.md — Build guide for HitKeep Cloud ## Project scope Deploy the official self-hostable HitKeep release, configure one site and add its documented tracker. Focus on HTTPS, retention, backups and a documented upgrade path rather than reimplementing analytics. Catalogue verdict: yes. The subscription is managed hosting of the same MIT-licensed application, so an agent does not need to reproduce HitKeep. It can deploy the official binary or container in one sitting; the real gap is upgrades, backups, email delivery, monitoring, and being on call for the analytics box. Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope. ## Working agreement - Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture. - Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled. - After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran. - Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply. - Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization. ## Prerequisites - A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. - Implementation components: Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. - Scope boundary: Hosted support, managed upgrades and service availability commitments remain the operator's responsibility. ## Stack and architecture - Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. - Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. - Operating records: official HitKeep release configuration, site registrations, tracker settings, persistent volumes and backup manifests ## Security and data integrity - Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. - Correctness boundary: Use only release-documented ports, variables and storage paths; a running container is not proof that events are being stored. - Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. - Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. ## Agent implementation rules - Project rule — operating records: official HitKeep release configuration, site registrations, tracker settings, persistent volumes and backup manifests - Project rule — preserve this invariant: Use only release-documented ports, variables and storage paths; a running container is not proof that events are being stored. - Project rule — acceptance evidence: Send a clearly labeled fixture event to a staging site, find it in the dashboard and restore that instance into separate volumes. ## Optional agent skills and references - Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. - Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism. ## Distribution ideas These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone. - Demonstrate the actual HitKeep Cloud-inspired workflow with owned or clearly labeled sample data: Deploy the official self-hostable HitKeep release, configure one site and add its documented tracker. Focus on HTTPS, retention, backups and a documented upgrade path rather than reimplementing analytics. - Publish a reproducible walkthrough with this observable result: Send a clearly labeled fixture event to a staging site, find it in the dashboard and restore that instance into separate volumes. - Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: Hosted support, managed upgrades and service availability commitments remain the operator's responsibility. Avoid guaranteed savings, performance scores or implied endorsement. ## Engineering roadmap 1. Phase 1 — Select and document the upstream release. Deploy the official self-hostable HitKeep release, configure one site and add its documented tracker. Focus on HTTPS, retention, backups and a documented upgrade path rather than reimplementing analytics. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Hosted support, managed upgrades and service availability commitments remain the operator's responsibility. 2. Phase 2 — Configure the maintained application. Record official HitKeep release configuration, site registrations, tracker settings, persistent volumes and backup manifests Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Use only release-documented ports, variables and storage paths; a running container is not proof that events are being stored. 3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. 4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate. 5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files. 6. Phase 6 — Operator handoff and acceptance. Send a clearly labeled fixture event to a staging site, find it in the dashboard and restore that instance into separate volumes. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting. ## Paid-product capabilities outside this build - managed upgrades and monitoring - encrypted regional backups - managed email delivery - vendor support and incident response ## Implementation prompt WORKING SLICE Deploy the official self-hostable HitKeep release, configure one site and add its documented tracker. Focus on HTTPS, retention, backups and a documented upgrade path rather than reimplementing analytics. Operate this scoped HitKeep Cloud-inspired deployment through the maintained upstream application. Record its configuration and failure states; do not rebuild its schema, interface or services. Architecture - Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. - Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. Prerequisites and limits A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. Outside this release: Hosted support, managed upgrades and service availability commitments remain the operator's responsibility. Configuration and correctness official HitKeep release configuration, site registrations, tracker settings, persistent volumes and backup manifests Invariant: Use only release-documented ports, variables and storage paths; a running container is not proof that events are being stored. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. Security and privacy Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Recovery and export Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Implementation order 1. Phase 1 — Select and document the upstream release. Deploy the official self-hostable HitKeep release, configure one site and add its documented tracker. Focus on HTTPS, retention, backups and a documented upgrade path rather than reimplementing analytics. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Hosted support, managed upgrades and service availability commitments remain the operator's responsibility. 2. Phase 2 — Configure the maintained application. Record official HitKeep release configuration, site registrations, tracker settings, persistent volumes and backup manifests Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Use only release-documented ports, variables and storage paths; a running container is not proof that events are being stored. 3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. 4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate. 5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files. 6. Phase 6 — Operator handoff and acceptance. Send a clearly labeled fixture event to a staging site, find it in the dashboard and restore that instance into separate volumes. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting. Acceptance Send a clearly labeled fixture event to a staging site, find it in the dashboard and restore that instance into separate volumes. Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees. Optional agent guidance Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Project rule — operating records: official HitKeep release configuration, site registrations, tracker settings, persistent volumes and backup manifests Project rule — preserve this invariant: Use only release-documented ports, variables and storage paths; a running container is not proof that events are being stored. Project rule — acceptance evidence: Send a clearly labeled fixture event to a staging site, find it in the dashboard and restore that instance into separate volumes. ## Completion evidence Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.