Skip to content

README.md

Latest commit

 

History

History
116 lines (94 loc) · 10.4 KB

README.md

File metadata and controls

116 lines (94 loc) · 10.4 KB
Raw

PromptPanel Documentation

Updated: 2026-06-10

This documentation set is now part of the public open-source repository. It is intended to let a new maintainer understand, build, verify, release, troubleshoot, and extend PromptPanel without relying on private handoff notes. Public entry points use Chinese-first wording with English technical terms where useful, so both traditional search engines and AI answer engines can identify the project accurately.

PromptPanel is a native, local-first macOS prompt manager and snippet launcher. The key workflow is:

global hotkey -> quick panel -> search -> execute -> clipboard guarantee -> automatic paste when allowed

Start Here

Document Purpose
Project introduction Public positioning, target users, feature boundary, and open-source entry map.
Architecture System shape, layers, dependencies, startup flow, and design boundaries.
Core modules and logic Code map, main modules, search, execution, settings, and UI contracts.
API and feature contract User-facing feature contracts, internal service APIs, database schema, script interfaces, and search behavior.
Configuration Settings, environment variables, build flags, storage paths, and permissions.
Deployment What "deployment" means for a local macOS app, packaging, CI, signing, notarization, and update hosting.
Development standards Local setup, code organization, Swift style, UI rules, testing, docs sync, and PR expectations.
Usage examples Practical AI workflow, coding, terminal, QA, restore, and docs-maintenance examples.
Operations and troubleshooting Runtime diagnosis, logs, paste failures, database recovery, and rollback thinking.
Maintainer handoff guide First-day maintainer workflow, code map, validation, release, troubleshooting, and extension rules.
Docs/code sync matrix Which docs to update for each code, script, config, release, or UI baseline change.
scripts/check-docs.sh Executable documentation gate for required pages, stale wording, search metadata, AI index coverage, and local link integrity.
OpenSpec documentation spec Current SDD baseline for the documentation system and handoff requirements.
OpenSpec change: complete project docs Change record for the documentation-system consolidation work.
Release and recovery Release-readiness flow, backup/restore boundary, signing, notarization, and recovery drill.
Roadmap and contribution guide Scoped roadmap, non-goals, issue/PR flow, and validation matrix.
Regression checklist Pre-release behavior and compatibility checks.
Compatibility regression log Real target-app compatibility samples and paste behavior notes.
Acceptance checklist UI, migration, release, and runtime acceptance points used during hardening.
Technical decisions Why PromptPanel uses Swift, AppKit/SwiftUI, SQLite/GRDB, KeyboardShortcuts, and Sparkle.
AI search and discoverability Repository wording, AI-search keywords, and LLM/SEO maintenance rules.
Search metadata JSON-LD Schema.org metadata block for a future website, docs site, or repository-aware search system.
Root directory cleanup log Current root layout boundary, moved entry points, and recyclable build-output cleanup.

Chinese-language handoff docs are intentionally kept because the original product definition and maintainer notes are Chinese. The root README and FAQ provide the English public entry layer.

Repository Entry Points

  • Root README: public product overview and build instructions.
  • Chinese README: Chinese public product overview.
  • FAQ: search-friendly explanations for common user questions.
  • llms.txt: short machine-readable project index.
  • llms-full.txt: expanded LLM context.
  • codemeta.json: structured open-source software metadata.
  • Schema.org JSON-LD: structured metadata for search engines and AI retrieval systems.
  • PRD: product scope and permanent non-goals.
  • Contributing: contribution rules and validation expectations.
  • Security: private reporting and local-data boundaries.

Current System Facts

  • Runtime shape: local macOS desktop app only.
  • UI language: Simplified Chinese only (CFBundleDevelopmentRegion = zh-Hans, no localization resources, no in-app language switch). The documentation is published in eight languages, so every public positioning surface must disclose this; scripts/check-docs.sh enforces it.
  • Source root: Sources/PromptPanel.
  • Tests: Tests/PromptPanelTests.
  • UI source of truth: frontend-draft/.
  • SDD source of truth for documentation-system work: openspec/specs/project-documentation/spec.md plus active/archived change records under openspec/changes/.
  • Build and release scripts: scripts/.
  • CI: .github/workflows/macos-release-readiness.yml.
  • Docs gate: scripts/check-docs.sh, also run by scripts/release-readiness.sh and CI.
  • Local database: ~/Library/Application Support/PromptPanel/promptpanel.db.
  • Logs: ~/Library/Logs/PromptPanel/.
  • Core guarantee: selected content is written to clipboard before automatic paste is attempted.
  • Accessibility permission is required only for automatic paste, not for clipboard fallback.
  • JSON library import is transactional: project and entry writes must either all succeed or all roll back after the write-before backup is created.
  • Quick panel ranking follows the same stable ordering contract as repository browsing: pin, manual sortOrder, recency, usage, current project, update time, id.

Documentation Sync Rules

Update docs in the same pull request when these areas change:

Change area Documents to update
Hotkey, panel lifecycle, activation, focus, or quick panel UI Architecture, Core modules and logic, Regression checklist
Database, migrations, backup, restore, or storage paths Configuration, Operations and troubleshooting, Release and recovery
Paste automation, clipboard behavior, permissions, or execution logs Core modules and logic, Operations and troubleshooting, Compatibility regression log
Build, signing, notarization, Sparkle, or GitHub Actions Deployment, Release and recovery, Configuration
Public feature behavior, usage examples, or internal service contracts API and feature contract, Usage examples, Core modules and logic
Development workflow, tests, dependency policy, or PR expectations Development standards, Contributing, Roadmap and contribution guide
Product positioning, target users, non-goals, or SEO/AI-search wording Root README, Chinese README, the six other localized READMEs, FAQ, AI search and discoverability, llms.txt, llms-full.txt, codemeta.json, Schema.org JSON-LD
UI strings, localization resources, or CFBundleDevelopmentRegion Every surface listed in the row above — the Simplified-Chinese-only UI disclosure is asserted by scripts/check-docs.sh and must be removed everywhere at once if a localized UI ships
Documentation structure, handoff workflow, or sync policy Maintainer handoff guide, Docs/code sync matrix, Development standards, this index

For development tasks, add or update an OpenSpec change before implementation when the change affects architecture, runtime behavior, data contracts, release/operations, or the maintained documentation baseline. Emergency production mitigation can be documented after the stopgap, but the change record and affected docs must still be backfilled.

After any code, script, CI, packaging, config, or UI-baseline change, run:

./scripts/check-docs.sh

This is not a full semantic proof, but it catches the failures that have caused real drift here: missing handoff pages, broken local links, undocumented PROMPTPANEL_* knobs, stale database names, old hotkey text, machine-local paths, missing AI-search metadata, and disconnected README/docs/llms entry points.

First-Day Maintainer Checklist

  1. Run git status --short to understand local drift.
  2. Run ./scripts/check-docs.sh.
  3. Run swift build.
  4. Run swift test if the host has full XCTest support. If the host lacks xctest, use the documented build-only readiness path and say so.
  5. Run ./scripts/release-readiness.sh --output-dir /tmp/promptpanel-ready-check for release-oriented validation.
  6. Build the .app with ./scripts/build-app.sh and smoke test the packaged app, not only the command-line binary.
  7. Check the main window's Runtime Health and recent execution logs after a real paste test.

Boundaries To Preserve

  • PromptPanel is a local macOS client, not a server product.
  • Containers and ordinary servers can host release files, but they do not run the product.
  • Clipboard write is the reliability guarantee; automatic paste is a best-effort convenience.
  • Database corruption recovery and schema migration failure are different incident classes.
  • Cloud sync, team collaboration, and workflow orchestration remain permanent non-goals.