Refresh documentation and supporting scripts#32
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a95d94987b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # JWT_SECRET_KEY | ||
| if [ -n "$JWT_SECRET_KEY" ] && [ "$JWT_SECRET_KEY" != "your-super-secret-jwt-key-change-this-in-production" ]; then | ||
| if [ -n "$JWT_SECRET_KEY" ] && [ "$JWT_SECRET_KEY" != "your-secret-key-change-in-production-please" ]; then | ||
| print_success "JWT_SECRET_KEY 已設定" |
There was a problem hiding this comment.
The updated check only flags the new default value (your-secret-key-change-in-production-please) as insecure, so environments still using the old default (your-super-secret-jwt-key-change-this-in-production) will now be reported as “已設定” even though they remain unsafe. This is a regression for anyone who copied the earlier .env template or has not rotated the key yet, since check-env.sh is meant to surface that risk. Consider treating both known defaults as insecure (or checking against a list) so the warning still triggers for pre-existing setups.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR refreshes the project’s documentation set (overview/getting started/usage/deployment/troubleshooting) and aligns supporting scripts and guides with the current API and deployment conventions (notably username-based login, spec/project_type, and Docker Compose v2 usage).
Changes:
- Updated scripts for production deploy and GCE deployment verification (env-var driven configuration, compose variable exports).
- Rewrote/added core docs (
OVERVIEW,GETTING_STARTED,CONFIGURATION,USAGE,DEPLOYMENT,TROUBLESHOOTING) and refreshed existing references. - Updated API examples across docs/CLI to reflect current auth/project payloads and added/archived supporting notes and reports.
Reviewed changes
Copilot reviewed 25 out of 31 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/verify-deployment.sh | GCE deployment verification script now env-var driven and checks container/ports/health. |
| scripts/deploy-prod.sh | Exports env vars needed by docker compose for prod image/volume interpolation. |
| scripts/check-env.sh | Updates default JWT secret comparison to match refreshed .env.example. |
| docs/testing/TEST_REPROVISION.md | Updates reprovision test flow and request payload fields (username, project_type, spec, /reprovision). |
| docs/testing/QUICK_TEST.md | Updates login example to use username. |
| docs/testing/POSTGRES_PERSISTENCE_VERIFICATION.md | Updates Docker Compose commands to v2 syntax (docker compose). |
| docs/testing/CHAT_FEATURE_TEST.md | Updates compose commands and request payload fields (username, spec). |
| docs/archives/reports/TEST_RESULTS.md | Adds archived Postgres persistence test results report. |
| docs/archives/reports/POSTGRES_MIGRATION_SUMMARY.md | Adds archived Postgres persistence migration summary. |
| docs/archives/reports/ENV_UPDATE_SUMMARY.md | Adds archived environment variable update summary. |
| docs/archives/reports/CHANGELOG_UX_IMPROVEMENTS.md | Fixes paths in archived UX improvements changelog to point to archived notes. |
| docs/archives/notes/VERTEX_AI_INTEGRATION.md | Adds archived Vertex AI integration planning note. |
| docs/archives/notes/UX_IMPROVEMENTS.md | Adds archived UX improvements note (auto-reconnect, toast, panel behavior). |
| docs/archives/notes/TESTING_UX_IMPROVEMENTS.md | Fixes health endpoint path in archived UX testing note. |
| docs/VERTEX_AI.md | Adds optional Vertex AI setup doc (ADC / SA JSON handling overview). |
| docs/USAGE.md | Adds consolidated usage guide for auth/project/provision/agent run/stream. |
| docs/TROUBLESHOOTING.md | Adds troubleshooting guide aligned with current endpoints and deployment model. |
| docs/RUN_AND_DEV.md | Adds run/dev quick reference for scripts, base image, and workspace mounts. |
| docs/README.md | Replaces docs index with a slimmer, task-oriented navigation structure. |
| docs/OVERVIEW.md | Adds high-level system overview and architecture/data-flow summary. |
| docs/GETTING_STARTED.md | Adds updated getting started flows (compose and local-dev). |
| docs/DEPLOYMENT.md | Adds deployment overview and manual host deployment steps for prod compose. |
| docs/CONFIGURATION.md | Adds configuration reference for backend/.env (required and optional). |
| docs/BACKEND.md | Updates backend doc to reflect current models/fields and health endpoint. |
| docs/API.md | Updates API spec examples (username login, spec/project_type) and adds Chat API section. |
| cli.py | Updates CLI login to use username, and project creation payload to use spec/project_type. |
| README.md | Refreshes root README quickstart, examples, and testing commands. |
| CLAUDE.md | Updates project notes/examples to reflect spec and compose v2 commands. |
| .github/workflows/README.md | Updates workflow README references and compose command syntax. |
| .github/workflows/GCE_DEPLOY.md | Updates GCE deployment guide to use backend/.env, new env vars, and new health endpoint path. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| echo "Port check:" | ||
| gcloud compute ssh "$INSTANCE" \ | ||
| --zone="$ZONE" \ | ||
| --project="$PROJECT_ID" \ | ||
| --command="(command -v ss >/dev/null 2>&1 && sudo ss -tulpn || sudo netstat -tulpn) | grep -E '(5432|27017|8000|80)' || echo 'No port conflicts found'" |
There was a problem hiding this comment.
Port check grep no longer includes port 5433, but the GCE deploy workflow maps Postgres to 127.0.0.1:5433 on the VM. This script can miss a 5433 conflict (or fail to show that Postgres is bound as expected). Include 5433 in the port pattern (and keep 5432) so the check matches the actual deployment setup.
| { | ||
| "status": "healthy", | ||
| "timestamp": "2026-02-02T12:00:00Z" | ||
| "status": "ok", | ||
| "timestamp": "2026-02-02T12:00:00Z", | ||
| "database": "healthy" | ||
| } |
There was a problem hiding this comment.
The health check JSON example shows a timestamp ending with Z, but the actual implementation uses datetime.utcnow().isoformat() (no trailing Z / timezone offset). Update the example to match the real format (or explicitly document that it’s UTC and show the exact emitted format).
Summary
Testing