fix: Improve codespace UX - README and terminal handling

.devcontainer/Dockerfile

@@ -48,6 +48,7 @@ RUN --mount=type=bind,target=/src \
     curl -sSL https://pdm-project.org/install-pdm.py | python3 - && \
     curl -LsSf https://astral.sh/uv/install.sh | sh && \
     echo 'export PATH="/home/user/.local/bin:$PATH"' >> ~/.bashrc && \
+    echo 'export PS1="\W\$ "' >> ~/.bashrc && \
     echo 'eval "$(pdm venv activate in-project 2>/dev/null || true)"' >> ~/.bashrc && \
     echo '' >> ~/.bashrc && \
     echo '# Run post-create setup once per codespace' >> ~/.bashrc && \

.devcontainer/devcontainer.json

@@ -25,11 +25,15 @@
         "github.copilot.inlineSuggest.enable": false,
         "chat.commandCenter.enabled": false,
         "chat.agent.enabled": false,
-        "workbench.startupEditor": "readme"
+	"chat.disableAIFeatures": true,
+        "workbench.startupEditor": "readme",
+        "extensions.ignoreRecommendations": true,
+        "git.autofetch": false
       },
       "extensions": [
         "ms-python.python",
-        "-github.copilot-chat"
+        "-github.copilot-chat",
+        "github.vscode-github-actions"
       ]
     }
   },
@@ -40,15 +44,6 @@
   // Run during prebuild - installs Python dependencies (cached!)
   "onCreateCommand": "bash .devcontainer/install-deps.sh",
 
-  // Post-create logic runs via .bashrc to avoid race condition with user terminal
-  // See: https://code.visualstudio.com/remote/advancedcontainers/start-processes#_adding-startup-commands-to-the-docker-image-instead
-
-  // Use 'postStartCommand' to run commands after the container starts
-  "postStartCommand": "echo 'ChipFlow development environment is ready!'",
-
-  // Open README.md when user attaches to the codespace
-  "postAttachCommand": "code README.md",
-
   // Container optimizations
   "containerEnv": {
     "PYTHONUNBUFFERED": "1",

.devcontainer/first-run-notice.txt

@@ -1,7 +1 @@
-🎉 ChipFlow codespace is ready!
-
-Quick commands:
-  • F5 or Cmd/Ctrl+Shift+B - Build and run simulation
-  • chipflow --help - ChipFlow CLI help
-  • pdm run --list - See all available commands
-
+🎉 ChipFlow codespace is starting up, please wait!...

.devcontainer/post-create.sh

@@ -14,14 +14,11 @@ cat << EOF > ~/.vscode.settings
 }
 EOF
 
-# simple prompt..
-export PS1="\W\$ "
-
 # Ensure PDM is in PATH and venv auto-activation is configured
 export PATH="/home/user/.local/bin:$PATH"
 eval "$(pdm venv activate in-project 2>/dev/null || true)"
 
-# Configurator API base URL (can be overridden via environment)
+# Configurator API base URL (will be set from design config if in codespace)
 CONFIGURATOR_API="${CHIPFLOW_CONFIGURATOR_API:-https://configurator.chipflow.io}"
 
 # Check if we're in a codespace and can fetch design from configurator
@@ -55,29 +52,22 @@ if [ -n "$CODESPACE_NAME" ]; then
 #    pdm config cache_dir ~/.cache/pdm
 #
     # Copy yowasp cache from Docker image
-    echo "🔥 Copying yowasp-yosys cache..."
+    echo "🔥 Synchronizing caches..."
     if [ -d /opt/chipflow-cache/yowasp ] && [ "$(ls -A /opt/chipflow-cache/yowasp)" ]; then
-        rm -rf ~/.cache/YoWASP
         mkdir -p ~/.cache/YoWASP
-        cp -r /opt/chipflow-cache/yowasp/* ~/.cache/YoWASP/
-        echo "✅ yowasp-yosys cache copied"
+        rsync -tr /opt/chipflow-cache/yowasp/* ~/.cache/YoWASP/ && echo "  ✅ yowasp-yosys cache copied"
     else
-        echo "⚠️  No yowasp cache found"
+        echo "  ⚠️  No yowasp cache found"
     fi
 
     # Copy zig cache from Docker image
-    echo "🔥 Copying zig cache..."
     if [ -d /opt/chipflow-cache/zig ] && [ "$(ls -A /opt/chipflow-cache/zig)" ]; then
-        rm -rf ~/.cache/zig
         mkdir -p ~/.cache/zig
-        cp -r /opt/chipflow-cache/zig/* ~/.cache/zig/
-        echo "✅ zig cache copied"
+        rsync -tr /opt/chipflow-cache/zig/* ~/.cache/zig/ && echo "  ✅ zig cache copied"
     else
-        echo "⚠️  No zig cache found"
+        echo "  ⚠️  No zig cache found"
     fi
 
-    echo "✅ Fixing cache permissions"
-    chmod -R u+w ~/.cache
 
     for attempt in $(seq 1 $MAX_RETRIES); do
         echo "Attempt $attempt/$MAX_RETRIES..."
@@ -103,6 +93,33 @@ if [ -n "$CODESPACE_NAME" ]; then
         # Save design.json
         echo "$DESIGN_BODY" | jq -r '.designData' > design.json
 
+        # Extract config from response (contains configuratorApi and welcomeUrl)
+        CHIPFLOW_CONFIGURATOR_API=$(echo "$DESIGN_BODY" | jq -r '.config.configuratorApi // "https://configurator.chipflow.io"')
+        CHIPFLOW_WELCOME_URL=$(echo "$DESIGN_BODY" | jq -r '.config.welcomeUrl // empty')
+
+        # Export to current environment
+        export CHIPFLOW_CONFIGURATOR_API
+        export CHIPFLOW_WELCOME_URL
+
+        # Update CONFIGURATOR_API with value from config
+        CONFIGURATOR_API="$CHIPFLOW_CONFIGURATOR_API"
+
+        # Save to .env file for sourcing by new terminals
+        cat > ~/.chipflow.env << EOF
+export CHIPFLOW_CONFIGURATOR_API="$CHIPFLOW_CONFIGURATOR_API"
+export CHIPFLOW_WELCOME_URL="$CHIPFLOW_WELCOME_URL"
+EOF
+
+        # Source the env file from bashrc if not already done
+        if ! grep -q "source ~/.chipflow.env" ~/.bashrc 2>/dev/null; then
+            echo "" >> ~/.bashrc
+            echo "# ChipFlow configuration (auto-generated)" >> ~/.bashrc
+            echo "if [ -f ~/.chipflow.env ]; then source ~/.chipflow.env; fi" >> ~/.bashrc
+        fi
+
+        # Source immediately for current session
+        source ~/.chipflow.env
+
         # Fetch generated files from API
         echo "🔨 Generating design files..."
         FILES_RESPONSE=$(curl -s -X POST "${CONFIGURATOR_API}/api/design/generate" \
@@ -160,6 +177,36 @@ if [ -f ".venv/bin/activate" ]; then
     echo "✅ PDM virtual environment is active"
     echo ""
 fi
+
+# Display welcome page URL if available
+if [ -n "$CHIPFLOW_WELCOME_URL" ]; then
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "📖 Getting Started Guide"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "🌐 Opening welcome page in browser..."
+    echo "   $CHIPFLOW_WELCOME_URL"
+    echo ""
+    echo "   The page includes:"
+    echo "   • Your design configuration"
+    echo "   • Copy-paste commands to get started"
+    echo "   • Links to documentation"
+    echo ""
+
+    # Auto-open in browser (GitHub Codespaces command)
+    # This works in both web and desktop VS Code Codespaces
+    if command -v gp >/dev/null 2>&1; then
+        # Gitpod/Codespaces browser opener
+        gp preview "$CHIPFLOW_WELCOME_URL" >/dev/null 2>&1 &
+    elif command -v python3 >/dev/null 2>&1; then
+        # Fallback: use python webbrowser module
+        python3 -c "import webbrowser; webbrowser.open('$CHIPFLOW_WELCOME_URL')" >/dev/null 2>&1 &
+    fi
+
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+fi
+
 echo "Quick commands:"
 echo "  • F5 or Cmd/Ctrl+Shift+B - Build and run simulation"
 echo "  • chipflow --help - ChipFlow CLI help"
@@ -168,4 +215,3 @@ echo ""
 echo "Entering venv:"
 pdm config check_update false
 eval $(pdm venv activate)
-cat .devcontainer/first-run-notice.txt

.github/workflows/pr-comment-test-link.yml

@@ -0,0 +1,70 @@
+name: PR Comment - Test Link
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  comment-test-link:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Comment test link
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const branch = context.payload.pull_request.head.ref;
+            const prNumber = context.payload.pull_request.number;
+            const testUrl = `https://configurator.chipflow.io/?template_branch=${encodeURIComponent(branch)}`;
+
+            const comment = `## 🧪 Test this PR in a Codespace
+
+            Use the configurator with this PR's devcontainer changes:
+
+            **[Open Configurator with branch: \`${branch}\`](${testUrl})**
+
+            This will create a codespace using the devcontainer configuration from this PR branch.
+
+            ### How to test:
+            1. Click the link above
+            2. Configure your chip design in the configurator
+            3. Click "Generate & Simulate"
+            4. Authenticate with GitHub if prompted
+            5. A codespace will be created using the devcontainer from \`${branch}\`
+            6. Verify the codespace UX and functionality
+
+            ---
+
+            💡 **Tip:** You can also manually append \`?template_branch=${encodeURIComponent(branch)}\` to any configurator URL to test this branch.`;
+
+            // Check if we already commented
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user?.type === 'Bot' &&
+              comment.body?.includes('Test this PR in a Codespace')
+            );
+
+            if (botComment) {
+              // Update existing comment
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: comment
+              });
+            } else {
+              // Create new comment
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: comment
+              });
+            }

README.md

@@ -0,0 +1,97 @@
+# ChipFlow Project
+
+Welcome to your ChipFlow hardware design project! This repository was generated from the [ChipFlow Configurator](https://configurator.chipflow.io) and contains everything you need to simulate and verify your chip design.
+
+## Getting Started in Codespaces
+
+Your development environment is ready to use! Here's how to get started:
+
+### 1. Build Your Design
+
+```bash
+chipflow sim build
+```
+
+This command:
+- Generates Verilog from your chip configuration
+- Compiles the simulation executable
+- Prepares everything for running simulations
+
+### 2. Run Simulations
+
+```bash
+chipflow sim run
+```
+
+This will execute your design simulation and show the results.
+
+### 3. View Results
+
+After simulation, you can explore the generated files:
+- **Verilog sources**: Check the generated RTL code
+- **Waveforms**: View signal traces (if waveform dumping is enabled)
+- **Test results**: See simulation output and verification results
+
+### Need Help?
+
+- **ChipFlow Documentation**: [docs.chipflow.io](https://docs.chipflow.io)
+- **Report Issues**: [github.com/ChipFlow/chipflow-template/issues](https://github.com/ChipFlow/chipflow-template/issues)
+- **Configurator**: [configurator.chipflow.io](https://configurator.chipflow.io)
+
+---
+
+## Developer Documentation
+
+### Project Structure
+
+```
+.
+├── .devcontainer/       # Codespace/devcontainer configuration
+├── designs/             # Generated chip designs (created after build)
+├── pyproject.toml       # Python dependencies
+├── pdm.lock            # Locked dependency versions
+└── README.md           # This file
+```
+
+### ChipFlow Commands
+
+| Command | Description |
+|---------|-------------|
+| `chipflow sim build` | Build the simulation from your design configuration |
+| `chipflow sim run` | Run the compiled simulation |
+| `chipflow pin lock` | Lock pin assignments for your design |
+
+### Development Workflow
+
+1. **Modify Design**: Update your chip configuration through the configurator or directly edit design files
+2. **Build**: Run `chipflow sim build` to regenerate Verilog and compile
+3. **Simulate**: Run `chipflow sim run` to test your changes
+4. **Iterate**: Review results and repeat
+
+### Environment Details
+
+This devcontainer includes:
+- **Python 3.x** with PDM package manager
+- **ChipFlow toolchain** for hardware design
+- **Yosys** (via yowasp-yosys) for synthesis
+- **Zig** for compilation
+- Pre-warmed caches for fast startup
+
+### Testing Locally
+
+If you want to test the devcontainer locally with VS Code or other Docker-compatible tools:
+
+```bash
+# The devcontainer should work with any tool supporting the devcontainer spec
+code .  # Opens in VS Code with devcontainer support
+```
+
+### Contributing
+
+This is a template repository. If you find issues with the devcontainer setup or have suggestions:
+1. Visit [ChipFlow/chipflow-template](https://github.com/ChipFlow/chipflow-template)
+2. Open an issue or pull request
+
+---
+
+**Generated with ChipFlow** - [configurator.chipflow.io](https://configurator.chipflow.io)