Merge origin/ui: integrate website, banner, and metadata-aware CLI

Resolves divergence (2 local / 14 remote commits) on the ui branch by
merging origin/ui. Remote contributed the project_meta.json flow,
URL-based project-name extraction, the public website, and architecture
banner. Local contributed the UI-mode console suppression.

Conflict resolution in main.py: kept remote helpers and variable usage
(local versions referenced undefined `project_name` in scope and used
the `name` click option which can be None), then re-applied local's
intent by wrapping the `run` command's task-info prints in
`if not config.ui_mode`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Codegass

.github/workflows/pages.yml

@@ -0,0 +1,33 @@
+name: Deploy website to GitHub Pages
+
+on:
+  push:
+    branches: [ui]
+    paths:
+      - 'website/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./website
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -170,4 +170,6 @@ student_tasks/
 docs/bash_tool_enhancements.md
 
 plan/
-docs/
+docs/
+
+website/node_modules

README.md

@@ -3,6 +3,10 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+> ICSE-NIER ’26 paper: [Setup AGent (SAG)](https://doi.org/10.1145/3786582.3786818) — Wei et al. The paper will be available soon this April.
+
+
+
 **SAG (Setup-Agent)** is an advanced AI agent designed to fully automate the initial setup, configuration, and ongoing tasks for any software project. It operates within an isolated Docker environment, intelligently interacting with project files, shell commands, and web resources to transform hours—or even days—of manual setup into a process that takes just a few minutes.
 
 ## 🔦 Highlights
@@ -186,10 +190,95 @@ uv run sag shell sag-fastapi
 uv run sag remove sag-fastapi
 ```
 
+### 4. Debugging & Troubleshooting
+
+When a setup fails or you want to understand what the agent did, SAG provides several debugging tools:
+
+#### Enable Verbose Mode & Recording
+
+```bash
+# Run with verbose output for detailed logs
+uv run sag --verbose project https://github.com/example/repo.git
+
+# Save artifacts locally for post-run inspection
+uv run sag project https://github.com/example/repo.git --record
+
+# Combine both for maximum visibility
+uv run sag --verbose project https://github.com/example/repo.git --record
+```
+
+#### Inspect Container Context Files
+
+The agent stores execution context inside the container under `/workspace/.setup_agent/`:
+
+```bash
+# List all context files
+docker exec sag-<project> ls -la /workspace/.setup_agent/contexts/
+
+# Read the trunk context (main task list and overall status)
+docker exec sag-<project> cat /workspace/.setup_agent/contexts/trunk_*.json | python3 -m json.tool
+
+# Check specific task contexts for detailed execution history
+docker exec sag-<project> cat /workspace/.setup_agent/contexts/task_*.json | python3 -m json.tool
+
+# Search for errors across all context files
+docker exec sag-<project> grep -r "error\|failed\|ERROR" /workspace/.setup_agent/contexts/
+```
+
+#### Review Setup Reports
+
+```bash
+# List generated reports
+docker exec sag-<project> ls -la /workspace/setup-report-*.md
+
+# Read the setup report
+docker exec sag-<project> cat /workspace/setup-report-*.md
+```
+
+#### Check Session Logs (with --record)
+
+When using `--record`, artifacts are saved to local session logs:
+
+```bash
+# Find the session log directory
+ls -la logs/session_*/
+
+# Review the main session log
+cat logs/session_<timestamp>/main.log
+
+# Check for specific error patterns
+grep -r "BUILD FAILURE\|compilation error" logs/session_<timestamp>/
+```
+
+#### Common Debugging Scenarios
+
+| Scenario | What to Check |
+|---|---|
+| Build failed | `grep "BUILD FAILURE" /workspace/.setup_agent/contexts/*.json` |
+| Java version mismatch | `docker exec sag-<project> java -version` and check for `RequireJavaVersion` in logs |
+| Missing dependencies | `docker exec sag-<project> which mvn npm gradle` |
+| Empty tool outputs | Check if stderr is captured in context files |
+| Agent stuck in loop | Review trunk context TODO list for repetitive patterns |
+
+#### Interactive Debugging
+
+```bash
+# Connect to the container shell for manual investigation
+uv run sag shell sag-<project>
+
+# Inside the container, you can:
+# - Run build commands manually
+# - Check environment variables
+# - Inspect project files
+# - Review logs in /workspace/.setup_agent/
+```
+
 ## 🛠️ CLI Command Reference
 
 SAG provides a clean and powerful set of CLI commands.
 
+### Commands
+
 | Command | Description | Example |
 |---|---|---|
 | `sag project <url>` | Initializes the setup for a new project from a Git repository URL. | `sag project https://github.com/pallets/flask.git` |
@@ -200,9 +289,54 @@ SAG provides a clean and powerful set of CLI commands.
 | `sag version` | Displays SAG's version information. | `sag version` |
 | `sag --help` | Shows the help message. | `sag --help` |
 
-**Global Options:**
-- `--log-level [DEBUG|INFO|...]`: Overrides the log level set in the `.env` file.
-- `--log-file <path>`: Specifies a custom path for the log file.
+### Global Options
+
+| Option | Description |
+|---|---|
+| `--log-level [DEBUG\|INFO\|WARNING\|ERROR]` | Overrides the log level set in the `.env` file. |
+| `--log-file <path>` | Specifies a custom path for the log file. |
+| `--verbose` | Enable verbose debugging output with detailed logs. |
+
+### Command-Specific Options
+
+#### `sag project <url>`
+
+| Option | Description |
+|---|---|
+| `--name <name>` | Override the Docker container name (default: extracted from URL). **Note:** This only affects the Docker container/volume naming (`sag-<name>`), not the project directory name. The cloned repository will always use the directory name from the URL. |
+| `--goal <goal>` | Custom setup goal (default: auto-generated based on project name). |
+| `--record` | Save setup artifacts (contexts, reports) to local session logs for debugging and auditing. |
+
+**Example with custom Docker name:**
+```bash
+# Clone commons-cli but name the Docker container "cli-test"
+sag project https://github.com/apache/commons-cli.git --name cli-test
+
+# Result:
+# - Docker container: sag-cli-test
+# - Project directory: /workspace/commons-cli (always matches git repo name)
+# - To run tasks later: sag run sag-cli-test --task "..."
+```
+
+#### `sag run <name>`
+
+| Option | Description |
+|---|---|
+| `--task <description>` | **(Required)** The task or requirement for the agent to execute. |
+| `--max-iterations <n>` | Maximum number of agent iterations (overrides `SAG_MAX_ITERATIONS` from config). |
+| `--record` | Save setup artifacts (contexts, reports) to local session logs for debugging and auditing. |
+
+#### `sag shell <name>`
+
+| Option | Description |
+|---|---|
+| `--shell <path>` | Shell to use in the container (default: `/bin/bash`). |
+
+#### `sag remove <name>`
+
+| Option | Description |
+|---|---|
+| `--force` | Force removal without confirmation prompt. |
 
 ## ✅ Running Tests Locally
 
@@ -260,3 +394,21 @@ We warmly welcome contributions of all kinds! Whether it's a bug report, a featu
 ## 📝 License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Cite this work
+
+BibTeX:
+
+```bibtex
+@inproceedings{Wei2026SAG,
+  author    = {Wei, Chenhao and Zhao, Gengwu and Ye, Billy and Xiao, Lu and Li, Xinyi},
+  title     = {Setup AGent (SAG): A Dual-Model LLM Agent for Autonomous End-to-End Java Project Configuration},
+  booktitle = {Proceedings of the 48th International Conference on Software Engineering: New Ideas and Emerging Results (ICSE-NIER '26)},
+  year      = {2026},
+  address   = {Rio de Janeiro, Brazil},
+  publisher = {ACM},
+  isbn      = {979-8-4007-2425-1},
+  month     = apr,
+  doi       = {10.1145/3786582.3786818}
+}
+```