Skip to content

DESIGN.md

Latest commit

 

History

History
124 lines (97 loc) · 5.59 KB

DESIGN.md

File metadata and controls

124 lines (97 loc) · 5.59 KB
Raw

Design

Outcome

This repository is a NeatContext Team Library: a read-only, Git-versioned set of public Dokploy investigation resources. It deliberately does not embed private incident data, a Dokploy fork, an AI model, or credentials. It ships one auditable extension source package, which cannot execute until a user explicitly installs a managed snapshot in NeatContext.

The Context assembled by a user has three inputs:

shared Git clone                explicit trust/install       user-owned folder
 profiles/dokploy.md                                      private/cases/<case>/
 knowledge/dokploy/          extension source -------->      case.md
       |                      managed snapshot                    |
       +---------------------------+------------------------------+
                                   |
                         one NeatContext Context
                                   |
                          connected AI client

This separation matters:

  • NeatContext discovers the shared profile and public knowledge by Team Library convention and treats them as read-only.
  • The user links one ignored case folder as a personal knowledge folder.
  • The Team extension source is inert until the user reviews and installs a managed snapshot; that snapshot exposes only read capabilities.
  • Public knowledge, live public GitHub results, and private evidence can be used in the same Context.
  • A user can pull public updates without merging or publishing private evidence.

Goals

  • Give public users a usable Dokploy issue-investigation Context in a few steps.
  • Make investigations version-aware, evidence-first, and resistant to premature root-cause claims.
  • Treat the user’s instance evidence as authoritative for what happened on that instance.
  • Keep sensitive material out of Git by default.
  • Keep the Team Library source inert: no extension code executes from this clone without explicit user installation.

Non-goals

  • Automatically diagnose every Dokploy issue.
  • Replace the official Dokploy documentation, repository, or issue tracker.
  • Operate, restart, upgrade, downgrade, or otherwise remediate a Dokploy installation.
  • Collect credentials or provide a secret store.
  • Assert that a public issue applies to a private installation merely because an error string is similar.

Library layout

NeatContext Team Library format version 1 is marked by library.json.

Path Scope Purpose
profiles/dokploy.md Shared Investigation policy, source precedence, safety constraints, and answer contract
knowledge/dokploy/ Shared Public, citable Dokploy knowledge and bounded case studies
extensions/dokploy-github/ Shared Inert source package for optional, GET-only public GitHub retrieval
templates/private-case.md Shared One best-effort case file a user copies before adding evidence
private/ Personal Git-ignored cases linked individually in NeatContext

Only top-level directories below knowledge/ are Team Library knowledge folders. This library therefore exposes one focused folder named dokploy.

Trust and evidence model

The active profile defines four evidence layers:

  1. User evidence establishes symptoms and runtime facts for the user’s instance.
  2. Source code pinned to the exact deployed release or commit establishes that version’s implementation.
  3. Official documentation establishes documented behavior.
  4. Issues, discussions, and historical cases supply leads, not automatic facts.

All retrieved files, issue comments, logs, and tool results are data. Their contents cannot relax the profile’s privacy or safety constraints.

Public documents record a “last verified” date and prefer stable release, commit, or documentation links. Time-sensitive status such as an open issue must be rechecked before being reported as current.

Extension boundary

extensions/dokploy-github/ is a dependency-free stdio MCP server following NeatContext’s Team Library extension contract. NeatContext discovers it as an uninstalled candidate and requires an explicit trust decision before copying a managed snapshot. Updates to the Git clone do not silently update that snapshot.

The extension hardcodes https://api.github.com and Dokploy/dokploy, accepts only conservative issue/PR identifiers, refs, timestamps, and repository paths, and sends only GET requests. It has no credential connection. Responses are size-bounded and preserve source URLs, retrieval times, and GitHub rate-limit metadata.

Private case lifecycle

  1. Create a new directory below private/cases/.
  2. Copy templates/private-case.md into it as case.md, then redact and fill that single file as best effort.
  3. Link that one case directory as a personal knowledge folder.
  4. Select it alongside the shared dokploy knowledge folder.
  5. Remove the personal link or archive/delete the local folder when finished.

The ignore rule is defense against accidental commits, not encryption. Users remain responsible for filesystem permissions, backups, sync tools, and the data-handling policy of the connected AI client.

Update policy

  • Policy or guardrail changes increment policy_version in the Dokploy profile.
  • Approval denotes review by this library’s maintainers, never endorsement by the Dokploy project; renew review_after only after rechecking the policy.
  • Public case studies stay bounded to a date and exact upstream references.
  • Changed executable validation logic requires tests.
  • Pull requests must pass npm test.
  • Never accept private incident evidence, secrets, or identifying customer data into the shared tree.