docs(cli): document project binding precedence and deep doctor workflow

Author: digitallysavvy

README.md

@@ -21,7 +21,6 @@ The command model is intentionally layered:
 - `project` for remote Agora resources and env export
 - `auth` for login and session inspection
 - `config` for local CLI defaults
-- `add` hidden and reserved for future in-place integrations into an existing codebase
 
 ## Install / Build
 
@@ -107,10 +106,6 @@ Handles login, logout, and current session inspection.
 
 Reads and updates local CLI defaults such as output mode, log level, and browser behavior.
 
-### `add`
-
-Hidden and reserved for future in-place integrations into an existing application. It is intentionally not part of the normal help surface today.
-
 ## Common Workflows
 
 ### Onboard a new demo
@@ -176,6 +171,38 @@ The CLI also writes repo-local project metadata to:
 
 That allows the CLI to detect which Agora project a cloned demo is bound to even when you are working inside the repo later.
 
+## Repo-Local Project Binding
+
+Project resolution precedence is consistent across commands:
+1. explicit `--project` or positional project argument
+2. repo-local `.agora/project.json` resolved from the target repo path
+3. global CLI context from `agora project use`
+
+The `.agora/project.json` file is created or updated by:
+- `agora init`
+- `agora quickstart create ... --project ...`
+- `agora quickstart env write ...`
+
+It stores durable non-secret metadata:
+- `projectId`
+- `projectName`
+- `region`
+- `template`
+- `envPath`
+
+Examples:
+
+```bash
+# Inside a bound quickstart repo
+./agora project show --json
+
+# From any directory, target a repo path directly
+./agora quickstart env write /abs/path/to/my-go-demo --json
+
+# Rebind a repo to a different project
+./agora quickstart env write /abs/path/to/my-go-demo --project my-other-project --json
+```
+
 ## Automation / Agent Usage
 
 For scripts, CI, and agentic workflows:
@@ -260,14 +287,11 @@ Quickstart env injection requires a project with an app certificate. If the sele
 If a command needs a project and none is currently selected, either:
 
 ```bash
+./agora quickstart env write my-go-demo --project my-project
 ./agora project use my-project
 ```
 
-or pass `--project` explicitly:
-
-```bash
-./agora quickstart env write my-go-demo --project my-project
-```
+or run it inside a repo that already has `.agora/project.json`.
 
 ## Migration
 

docs/automation.md

@@ -17,6 +17,25 @@ Use this guide for:
 - Use `agora project doctor --json` for readiness checks before continuing with automated setup.
 - In JSON mode, both success and failure return the same top-level envelope shape.
 
+Primary command groups:
+- `init`
+- `quickstart`
+- `project`
+- `auth`
+- `config`
+
+## Project Resolution Precedence
+
+Commands that require a project resolve context in this order:
+1. explicit `--project` or positional project argument
+2. repo-local `.agora/project.json` from the target repo path
+3. global CLI context selected by `agora project use`
+
+Agent guidance:
+- prefer explicit `--project` for deterministic cross-repo operations
+- rely on repo-local binding when operating repeatedly inside one bound quickstart
+- keep `metadataPath` from command results if you need to validate or audit project bindings
+
 ## JSON Envelope
 
 Commands that support structured output return a JSON envelope in this shape:
@@ -328,7 +347,7 @@ Safe branch fields:
 Example:
 
 ```bash
-./agora quickstart env write my-python-demo --json
+./agora quickstart env write /abs/path/to/my-python-demo --json
 ```
 
 Required `data` fields:
@@ -382,6 +401,8 @@ Required `data` fields:
 Optional fields:
 - `project`
   Nil during auth or project-selection failure paths.
+- `workspace`
+  Present in deep mode with repo-local binding and env consistency details.
 
 Safe branch fields:
 - `healthy`
@@ -395,6 +416,7 @@ Recommended agent behavior:
 - branch first on `status`
 - use `healthy` as a fast readiness boolean
 - inspect `blockingIssues[].suggestedCommand` for recovery suggestions
+- for repo-bound validation, run `project doctor --deep --json`
 
 ### `auth status`