Skip to content

docs: rework repo for the end user (web UI) and trim developer docs - #2

Merged
briacSck merged 1 commit into
mainfrom
chore/crystal-handoff
Jun 20, 2026
Merged

briacSck merged 1 commit into
mainfrom
chore/crystal-handoff

Conversation

@briacSck

Copy link
Copy Markdown
Owner

Prepares the handoff to a non-technical macOS user who runs only the web UI.

User-facing:

  • Rewrite README.md as a plain-language, web-UI, macOS walkthrough: one-time setup (install uv, make a Mistral key, fill .env), each grading run (start script → browser → upload zip → download), and privacy cleanup when done.
  • Rewrite docs/data-policy.md in plain terms (what stays local, what is sent, check your Mistral retention setting, erase when done).
  • Ship a ready-to-use config.yaml (un-ignored; holds no secrets) with the validated masking regexes, auto_orient, and min_native_dpi=140, so she never edits YAML; course is set per-batch in the upload form.

Foolproof setup:

  • Load .env in-app via python-dotenv (web app + CLI), so the API key and the web login come from a file instead of shell env vars. Robust to special characters like '&' in the password (verified: .env-only login returns 200).
  • Add .env.example, and double-click macOS scripts start.command / cleanup.command (executable bit + .gitattributes eol=lf so they run on a Mac).

Cleanup:

  • Consolidate ARCHITECTURE + OPERATIONS + CHANGELOG into one concise MAINTAINERS.md.
  • Delete deployment docs (docs/deploy.md, Dockerfile), the 586-line PRD (ocr-grading-tool-plan.md), and fold docs/runbook.md + docs/mistral-setup.md into the README. All recoverable from git history.

Tests: 59 passing (unchanged). No student data or trial artifacts are tracked.

Prepares the handoff to a non-technical macOS user who runs only the web UI.

User-facing:
- Rewrite README.md as a plain-language, web-UI, macOS walkthrough: one-time
  setup (install uv, make a Mistral key, fill .env), each grading run (start
  script → browser → upload zip → download), and privacy cleanup when done.
- Rewrite docs/data-policy.md in plain terms (what stays local, what is sent,
  check your Mistral retention setting, erase when done).
- Ship a ready-to-use config.yaml (un-ignored; holds no secrets) with the
  validated masking regexes, auto_orient, and min_native_dpi=140, so she never
  edits YAML; course is set per-batch in the upload form.

Foolproof setup:
- Load .env in-app via python-dotenv (web app + CLI), so the API key and the
  web login come from a file instead of shell env vars. Robust to special
  characters like '&' in the password (verified: .env-only login returns 200).
- Add .env.example, and double-click macOS scripts start.command / cleanup.command
  (executable bit + .gitattributes eol=lf so they run on a Mac).

Cleanup:
- Consolidate ARCHITECTURE + OPERATIONS + CHANGELOG into one concise MAINTAINERS.md.
- Delete deployment docs (docs/deploy.md, Dockerfile), the 586-line PRD
  (ocr-grading-tool-plan.md), and fold docs/runbook.md + docs/mistral-setup.md
  into the README. All recoverable from git history.

Tests: 59 passing (unchanged). No student data or trial artifacts are tracked.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@briacSck
briacSck merged commit 98b4719 into main Jun 20, 2026
1 check passed
@briacSck
briacSck deleted the chore/crystal-handoff branch June 20, 2026 12:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant