Skip to content

OPERATIONS.md

Latest commit

 

History

History
144 lines (99 loc) · 6.36 KB

OPERATIONS.md

File metadata and controls

144 lines (99 loc) · 6.36 KB
Raw

Operations

AcademyLens is an open-source beta. Operational quality means repeatable evidence, not just a passing build.

Unofficial, not affiliated with OpenAI.

Release evidence is summarized in TRUST_EVIDENCE.md. Keep that page aligned with the runtime provider path, glossary status, live QA manifest, and release asset readiness before any public submission.

Routine Commands

Use these commands before a public release, store asset pass, or major glossary promotion:

npm run glossary:scoreboard
npm run check:full
npm run store:screenshots
npm run check:operations
npm run check:github-security
npm run release:preflight

npm run check:full is the product correctness gate. npm run release:preflight is the heavier operations gate: it runs the full product gate, generates local store screenshot drafts, and re-checks operations metadata.

Security Operations

GitHub repository security should keep vulnerability alerts, Dependabot security updates, secret scanning, and push protection enabled.

The CI workflow uses read-only repository permissions and disables checkout credential persistence. The CodeQL workflow analyzes JavaScript on pull requests, pushes to main, and a weekly schedule with security-events: write scoped only for SARIF upload.

The GitHub repository ruleset Protect main release gate protects the default branch with pull requests, strict required status checks, linear history, deletion protection, and non-fast-forward protection. Required checks are verify, Analyze JavaScript, and CodeQL.

Check the live GitHub settings after repo policy changes:

npm run check:github-security

This command requires an authenticated gh CLI with repository admin access. It intentionally stays out of release:preflight because GitHub settings checks should not depend on CI runner credentials.

Release zip builds write both:

dist/academy-lens.zip
dist/academy-lens.zip.sha256

Keep academy-lens.zip.sha256 beside every zip used for public release review.

Live Academy DOM QA

The required live QA surface list lives in LIVE_QA_MANIFEST.json. Treat it as the release checklist source of truth.

Before Chrome Web Store submission or a promotional push:

  1. Load AcademyLens as an unpacked extension in Chrome.
  2. Visit each surface listed in requiredBeforeStore.
  3. Confirm Translate and Restore work on visible course or lesson content.
  4. Confirm Gradual controls remain usable and untranslated: navigation, search, account, enrollment, progress, certificate, quiz, status, and CTAs.
  5. Capture a sanitized fixture only when it improves automated coverage.
  6. Do not commit screenshots or fixtures with account names, profile images, notifications, progress, certificates, tokens, emails, or telemetry metadata.

Use the capture helper for reviewed fixture candidates:

npm run qa:live

The command writes to /tmp by default and prints a redaction report. To intentionally write under tests/fixtures, first review the output and then rerun npm run capture:academy with --allow-fixture-write.

Glossary Operations

The current glossary board is generated in GLOSSARY_STATUS.md.

When glossary metadata or terms change:

npm run glossary:scoreboard
npm run check:glossary
npm run check:glossary-status
npm run check:glossary-overreach

Promotion rules:

  • llm-drafted is allowed as early beta correction data, but public copy must call it AI-drafted beta.
  • llm-audited requires a recorded second-pass high-risk terminology audit and passing npm run check:glossary-quality; public copy can call it AI-audited beta.
  • community-reviewed requires fluent community review evidence.
  • native-reviewed requires native-speaker review evidence.
  • reviewed requires complete official alignment, closed X translation check, closed community/native review, and passing smoke tests.
  • Do not promote a language just because it has the same term count as other packs.

Provider And Privacy Audit

Current runtime behavior:

  • Browser-native Translator API is used when already available, or when the user explicitly allows browser-managed translator downloads.
  • Google Translate endpoint is the fallback translation provider.
  • Translation cache entries are scoped by provider and glossary state; local corrections bypass cached provider text.
  • Correction management and runtime diagnostics are local-only browser storage/UI features.
  • GPT/Puter/OpenAI review is disabled.
  • No AcademyLens server is used.

Before public release:

  1. Confirm PRIVACY_POLICY.md still says extension-selected visible lesson text can be handled by browser-native Translator or sent to Google Translate fallback.
  2. Confirm store copy does not describe the endpoint as Google Cloud Translation API.
  3. Confirm runtime files do not load remote hosted SDK scripts.
  4. Confirm browser-native translator downloads remain explicit opt-in.
  5. Confirm local correction storage is described.
  6. Confirm diagnostics do not expose original or translated lesson text.
  7. Confirm AI review remains disabled unless there is explicit opt-in UX and updated privacy text.

Store Asset Operations

Draft fixture screenshots:

npm run store:screenshots

Outputs are written to dist/store-screenshots/, which is intentionally ignored. These are review drafts, not automatic release assets. The optional --path argument is restricted to fixture routes with explicit Translate/Restore assertions.

Final public screenshots should be reviewed manually for:

  • no private account details
  • no certificate, progress, notification, or profile data
  • visible unofficial notice
  • no claim of OpenAI affiliation
  • panel readable at desktop and mobile sizes

Contributor Operations

Useful external contributions:

  • locale glossary reviews
  • X translation cross-check notes
  • sanitized fixture improvements
  • live QA reports
  • accessibility and visual QA notes
  • public copy, README, store listing, and screenshot review improvements that keep the unofficial positioning clear

Every PR should keep the unofficial positioning intact, avoid remote hosted runtime code, and preserve protected terms. Final merge authority is intentionally centralized through CODEOWNERS while the project is pre-release; external reviewer evidence should be captured in issues, PR notes, QA reports, or glossary audit packets before status promotion.