ci: enhance Claude GitHub Actions and documentation (#1890)

* Claude PR Assistant workflow

* Claude Code Review workflow

* ci: enhance Claude GitHub Actions configuration

- Add comprehensive code review prompts for CryoET Data Portal
- Enable sticky comments and sequential thinking MCP
- Add context-aware review criteria for frontend and Python code
- Configure allowed tools for development commands
- Add detailed custom instructions for repository context

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: migrate Claude commands to repository root

- Move .claude/commands/ from frontend/ to repository root
- Add comprehensive CLAUDE.md with project overview and commands
- Remove duplicate command files from frontend directory
- Consolidate development guidance in single location

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: enhance frontend development documentation

- Add comprehensive command reference with individual linters
- Document E2E testing setup and browser installation
- Add CSS build tooling and typed CSS modules setup
- Include development workflow and testing configuration
- Document code quality standards and TypeScript setup

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: update PR creation to reference issues at top of body

- Move issue reference to the very top of PR body as #ISSUE_NUMBER
- Remove 'Closes #' keyword to avoid auto-closing issues
- Add clear example of PR body format with issue reference
- Clarify that issue number should be on its own line

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: codemonkey800

…ntend/.claude/commands/create-commits.md .claude/commands/create-commits.mdfrontend/.claude/commands/create-commits.md renamed to .claude/commands/create-commits.md frontend/.claude/commands/create-commits.md renamed to .claude/commands/create-commits.md

@@ -5,51 +5,74 @@ This command automates the creation of logical, well-structured commits with int
 ## Command Usage
 
 - `create-commits` - Basic usage with current branch
-- `create-commits --base develop` - Create commits with custom base branch reference
-
-### Flag Details
-
-- `--base <branch-name>` - Specify the base branch for reference (default: main)
-  - Useful when working with feature branches or dependent branches
-  - Helps determine which changes are new since branching from base
 
 ## Workflow
 
 ### 1. Branch Management
 
 - Check current branch name using `git branch --show-current`
-- Determine base branch (default: `main`, or value from `--base` flag)
-- Validate base branch exists: `git show-ref --verify refs/heads/<base-branch>` or `git ls-remote --heads origin <base-branch>`
+- Determine base branch (default: `main`)
+- Validate base branch exists: `git show-ref --verify refs/heads/main` or `git ls-remote --heads origin main`
 - If current branch is same as base branch:
   - Analyze staged and unstaged changes to determine scope
   - Create new branch with format: `<scope>/auto-<timestamp>-<short-description>`
   - Example: `feat/auto-20250625-dataset-metadata-updates`
 - If current branch is different from base branch:
   - Use existing branch for commit creation
-  - Verify branch is not behind remote base branch: `git merge-base --is-ancestor origin/<base-branch> HEAD`
+  - Verify branch is not behind remote base branch: `git merge-base --is-ancestor origin/main HEAD`
 
 ### 2. Pre-Commit Validation
 
 Execute the following commands in sequence and stop if any fail:
 
-- Run `pnpm lint` to check for linting issues
-- If linting fails, run `pnpm lint:fix` to auto-fix issues
-- Run `pnpm data-portal type-check` to verify TypeScript types
+**For Frontend Changes:**
+
+- Run `cd frontend && pnpm lint` to check for linting issues
+- If linting fails, run `cd frontend && pnpm lint:fix` to auto-fix issues
+- Run `cd frontend && pnpm data-portal type-check` to verify TypeScript types
 - If type check fails, report specific errors and require manual fixes before proceeding
 
+**For Python Client Changes:**
+
+- Run `cd client/python/cryoet_data_portal && make coverage` to run Python tests
+- If tests fail, report specific errors and require manual fixes before proceeding
+
+**For Documentation Changes:**
+
+- Run `cd docs && make html` to build documentation
+- If build fails, report specific errors and require manual fixes before proceeding
+
 ### 3. Change Analysis and Commit Splitting
 
 Analyze all staged and unstaged changes to intelligently group them:
 
 #### File Grouping Logic:
 
-- **UI Components**: Group `*.tsx` files in `/components/` together
-- **GraphQL Operations**: Group `*.server.ts` files in `/graphql/` together
-- **Type Definitions**: Group `__generated_v2__/**/*.ts` files together
-- **Translations**: Group `translation.json` changes separately
-- **Configuration**: Group config files (`*.config.*`, `package.json`, etc.) together
-- **Tests**: Group test files (`*.test.*`, `*.spec.*`) together
-- **Documentation**: Group `*.md` files together
+**Frontend Changes:**
+
+- **UI Components**: Group `frontend/**/*.tsx` files in `/components/` together
+- **GraphQL Operations**: Group `frontend/**/*.server.ts` files in `/graphql/` together
+- **Type Definitions**: Group `frontend/**/__generated_v2__/**/*.ts` files together
+- **Translations**: Group `frontend/**/translation.json` changes separately
+- **Frontend Config**: Group frontend config files (`frontend/**/*.config.*`, `frontend/package.json`, etc.) together
+- **Frontend Tests**: Group frontend test files (`frontend/**/*.test.*`, `frontend/**/*.spec.*`) together
+
+**Python Client Changes:**
+
+- **Python Source**: Group `client/python/**/*.py` files by module
+- **Python Tests**: Group `client/python/**/test_*.py` files together
+- **Python Config**: Group Python config files (`client/python/**/pyproject.toml`, `client/python/**/Makefile`, etc.) together
+
+**Documentation Changes:**
+
+- **Docs**: Group `docs/**/*.md`, `docs/**/*.rst` files together
+- **Website Docs**: Group `website-docs/**/*.mdx` files together
+
+**Repository-wide Changes:**
+
+- **Root Configuration**: Group root config files (`*.config.*`, `package.json`, `pyproject.toml`, etc.) together
+- **CI/CD**: Group `.github/**/*` files together
+- **Root Documentation**: Group root `*.md` files together
 
 #### Commit Creation Strategy:
 
@@ -98,25 +121,31 @@ For each commit group:
 
 ### Lint Failures:
 
-- Attempt auto-fix with `pnpm lint:fix`
+- Attempt auto-fix with `cd frontend && pnpm lint:fix`
 - If still failing, list specific errors and pause for manual resolution
 
 ### Type Check Failures:
 
 - Display TypeScript errors clearly
 - Require manual fixes before proceeding
-- Suggest running `pnpm data-portal build:codegen` if GraphQL types are stale
+- Suggest running `cd frontend && pnpm data-portal build:codegen` if GraphQL types are stale
+
+### Python Test Failures:
+
+- Display Python test errors clearly
+- Require manual fixes before proceeding
+- Suggest running `cd client/python/cryoet_data_portal && make test-infra` if test infrastructure needs setup
 
 ### Git Conflicts:
 
-- If branch is behind base branch, suggest rebasing first: `git rebase origin/<base-branch>`
+- If branch is behind base branch, suggest rebasing first: `git rebase origin/main`
 - If conflicts exist, pause and request manual resolution
 
 ### Base Branch Validation:
 
 - If specified base branch doesn't exist locally or remotely, list available branches and exit
 - If current branch is the same as base branch, require creation of new branch first
-- If base branch is not accessible, suggest fetching: `git fetch origin <base-branch>`
+- If base branch is not accessible, suggest fetching: `git fetch origin main`
 
 ### Empty Changes:
 
@@ -145,10 +174,10 @@ After successful commit creation:
 
 ### Base Branch Validation Requirements:
 
-1. **Branch Existence Check**: Verify base branch exists using `git show-ref --verify refs/heads/<base-branch>` (local) or `git ls-remote --heads origin <base-branch>` (remote)
-2. **Branch Accessibility**: Ensure base branch is up-to-date with remote: `git fetch origin <base-branch>`
+1. **Branch Existence Check**: Verify base branch exists using `git show-ref --verify refs/heads/main` (local) or `git ls-remote --heads origin main` (remote)
+2. **Branch Accessibility**: Ensure base branch is up-to-date with remote: `git fetch origin main`
 3. **Self-Reference Prevention**: Prevent creating commits when current branch equals base branch without creating new branch first
-4. **Branch Relationship Validation**: Check if current branch has diverged from base branch using `git merge-base <base-branch> HEAD`
+4. **Branch Relationship Validation**: Check if current branch has diverged from base branch using `git merge-base main HEAD`
 
 ## Workflow Summary
 

frontend/.claude/commands/create-pr.md .claude/commands/create-pr.mdfrontend/.claude/commands/create-pr.md renamed to .claude/commands/create-pr.md

@@ -19,6 +19,45 @@ This command automates the creation of pull requests from existing commits. It s
 - `--draft` - Create PR in draft mode
 - `--issue <number>` - Link PR to issue number
 
+## Argument Parsing
+
+```bash
+# Parse command line arguments
+DRAFT_FLAG=false
+ISSUE_NUMBER=""
+BASE_BRANCH="main"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --draft)
+            DRAFT_FLAG=true
+            shift
+            ;;
+        --issue)
+            ISSUE_NUMBER="$2"
+            shift 2
+            ;;
+        --issue=*)
+            ISSUE_NUMBER="${1#*=}"
+            shift
+            ;;
+        --base)
+            BASE_BRANCH="$2"
+            shift 2
+            ;;
+        --base=*)
+            BASE_BRANCH="${1#*=}"
+            shift
+            ;;
+        *)
+            echo "Unknown argument: $1"
+            shift
+            ;;
+    esac
+done
+```
+
 ## Prerequisites
 
 This command expects that `/create-commits` has been run first to create logical commits. The workflow will:
@@ -32,9 +71,9 @@ This command expects that `/create-commits` has been run first to create logical
 ### 1. Branch and Commit Validation
 
 - Check current branch name using `git branch --show-current`
-- Determine base branch (default: `main`, or value from `--base` flag)
-- Validate base branch exists: `git show-ref --verify refs/heads/<base-branch>` or `git ls-remote --heads origin <base-branch>`
-- Verify current branch is different from base branch
+- Determine base branch (using parsed BASE_BRANCH variable, default: `main`)
+- Validate base branch exists: `git show-ref --verify refs/heads/$BASE_BRANCH` or `git ls-remote --heads origin $BASE_BRANCH`
+- Verify current branch is different from base branch ($BASE_BRANCH)
 - Check for unpushed commits using `git log origin/<current-branch>..HEAD` or `git rev-list --count @{u}..HEAD`
 - If no unpushed commits exist, inform user and exit
 
@@ -44,32 +83,48 @@ This command expects that `/create-commits` has been run first to create logical
 - If branch doesn't exist on remote OR has unpushed commits, push: `git push -u origin <branch-name>`
 - Analyze existing commit messages to determine primary scope and generate PR title
 - Create PR body with:
+  - **Issue**: If ISSUE_NUMBER is provided, add "#$ISSUE_NUMBER" at the very top on its own line
   - **Summary**: Brief overview of changes made (derived from commit messages)
   - **Changes**: Bullet list of major modifications (from commit history)
   - **Testing**: Instructions for testing the changes
-  - **Issue Link**: If `--issue` flag provided, add "Closes #<number>"
 
 #### PR Title Generation:
 
-- Analyze commit messages from `git log <base-branch>..HEAD --oneline`
+- Analyze commit messages from `git log $BASE_BRANCH..HEAD --oneline`
 - Extract primary scope from most recent or most significant commit
 - Use format: `<primary-scope>: <concise-description>`
 - Example: `feat: add dataset metadata display functionality`
 
+#### PR Body Format:
+
+When ISSUE_NUMBER is provided, the PR body should start with the issue reference on its own line:
+```
+#1806
+
+## Summary
+Brief overview of changes...
+
+## Changes
+- List of modifications...
+
+## Testing
+- Testing instructions...
+```
+
+When no issue number is provided, start directly with the Summary section.
+
 #### PR Creation Command:
 
 ```bash
 gh pr create \
   --title "<scope>: <title>" \
   --body "<generated-body>" \
-  $(if draft flag: --draft) \
+  $(if $DRAFT_FLAG; then echo "--draft"; fi) \
   --head <branch-name> \
-  --base <base-branch>
+  --base $BASE_BRANCH
 ```
 
-Where `<base-branch>` is determined by:
-- Value from `--base` flag if provided
-- Default to `main` if no `--base` flag specified
+Where the base branch is determined by the parsed BASE_BRANCH variable (default: `main`)
 
 ## Error Handling
 
@@ -80,14 +135,14 @@ Where `<base-branch>` is determined by:
 
 ### Git Conflicts:
 
-- If branch is behind base branch, suggest rebasing first: `git rebase origin/<base-branch>`
+- If branch is behind base branch, suggest rebasing first: `git rebase origin/$BASE_BRANCH`
 - If conflicts exist, pause and request manual resolution
 
 ### Base Branch Validation:
 
 - If specified base branch doesn't exist locally or remotely, list available branches and exit
 - If current branch is the same as base branch, inform user they need to create commits on a feature branch first
-- If base branch is not accessible, suggest fetching: `git fetch origin <base-branch>`
+- If base branch is not accessible, suggest fetching: `git fetch origin $BASE_BRANCH`
 
 ### Push Failures:
 
@@ -100,24 +155,29 @@ After successful PR creation:
 
 1. Display PR URL
 2. Show commit summary with messages (from git log)
-3. Confirm if created as draft (if applicable)
-4. Show linked issue number (if applicable)
+3. Confirm if created as draft (if DRAFT_FLAG is true)
+4. Show linked issue number (if ISSUE_NUMBER is provided)
 5. Display instructions for next steps (review process, testing, etc.)
 
 ## Advanced Features
 
 ### PR Body Generation:
 
+- If issue number is provided, place it at the very top as "#ISSUE_NUMBER" on its own line
 - Parse commit messages to extract meaningful summary
 - Group related commits to describe feature scope
-- Include testing instructions based on changed files
+- Include testing instructions based on changed files:
+  - **Frontend changes**: Include `cd frontend && pnpm test` and `cd frontend && pnpm e2e`
+  - **Python client changes**: Include `cd client/python/cryoet_data_portal && make coverage`
+  - **Documentation changes**: Include `cd docs && make html`
+- Note: Do NOT use closing keywords like "Closes", "Fixes", or "Resolves" with issue references
 
 ### Base Branch Validation Requirements:
 
-1. **Branch Existence Check**: Verify base branch exists using `git show-ref --verify refs/heads/<base-branch>` (local) or `git ls-remote --heads origin <base-branch>` (remote)
-2. **Branch Accessibility**: Ensure base branch is up-to-date with remote: `git fetch origin <base-branch>`
+1. **Branch Existence Check**: Verify base branch exists using `git show-ref --verify refs/heads/$BASE_BRANCH` (local) or `git ls-remote --heads origin $BASE_BRANCH` (remote)
+2. **Branch Accessibility**: Ensure base branch is up-to-date with remote: `git fetch origin $BASE_BRANCH`
 3. **Self-Reference Prevention**: Prevent creating PR where current branch equals base branch
-4. **Branch Relationship Validation**: Check if current branch has diverged from base branch using `git merge-base <base-branch> HEAD`
+4. **Branch Relationship Validation**: Check if current branch has diverged from base branch using `git merge-base $BASE_BRANCH HEAD`
 
 ## Workflow Summary