(texera) branch gh-readonly-queue/main/pr-6015-50d520634a0bd6673c85e81882f1e050722e79f3 created (now 16a3ddfe58)

[gi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a change to branch gh-readonly-queue/main/pr-6015-50d520634a0bd6673c85e81882f1e050722e79f3
in repository https://gitbox.apache.org/repos/asf/texera.git


      at 16a3ddfe58 docs(agents): document the local dev stack and worktree workflow (#6015)

This branch includes the following new commits:

     new 16a3ddfe58 docs(agents): document the local dev stack and worktree workflow (#6015)

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

(texera) 01/01: docs(agents): document the local dev stack and worktree workflow (#6015)

[gi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-6015-50d520634a0bd6673c85e81882f1e050722e79f3
in repository https://gitbox.apache.org/repos/asf/texera.git

commit 16a3ddfe58fd7540d8ab5c9da88f0901cb804f4d
Author: Yicong Huang <17...@users.noreply.github.com>
AuthorDate: Sun Jun 28 18:56:21 2026 -0700

    docs(agents): document the local dev stack and worktree workflow (#6015)
    
    ### What changes were proposed in this PR?
    
    `AGENTS.md` documents the single-node and k8s deploy paths but never
    tells an agent how to run the local dev stack. This PR:
    
    - adds a "Where Things Live" row routing to `bin/local-dev.sh` — the
    single entry point (infra in Docker; backend, frontend, and
    agent-service run natively);
    - expands the "Develop in a worktree" section to:
      - prefer `bin/local-dev.sh` while developing;
    - bounce the stack across worktree switches (`down` in the old worktree,
    `up` in the new one), since the native services bind fixed ports and
    share one PID/state dir, so only one worktree's stack runs at a time;
    - use the non-interactive CLI subcommands — the interactive TUI (`-i`)
    is for humans, not agents.
    - drops "Local" from the single-node / k8s deploy row — both can deploy
    anywhere, not only locally.
    
    Only the wrapper is surfaced, never the internal
    `bin/local-dev/main.sh`.
    
    ### Any related issues, documentation, discussions?
    
    Closes #6014
    
    ### How was this PR tested?
    
    Docs-only change; no tests. Verified the linked
    `bin/local-dev/README.md` path resolves and that the described
    subcommands (`up` / `down` / `status` / `logs` / `-i`) match
    `bin/local-dev.sh --help`.
    
    ### Was this PR authored or co-authored using generative AI tooling?
    
    Generated-by: Claude Code (Claude Opus 4.8)
---
 AGENTS.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index eef0aea460..d537ffcbd8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,7 +34,8 @@ engine, an Angular UI, and the agent service. JVM modules wired in
 | PR template | [.github/PULL_REQUEST_TEMPLATE](.github/PULL_REQUEST_TEMPLATE) |
 | Issue templates | [bug](.github/ISSUE_TEMPLATE/bug-template.yaml) / [task](.github/ISSUE_TEMPLATE/task-template.yaml) / [feature](.github/ISSUE_TEMPLATE/feature-template.yaml) |
 | License-header coverage; vendored `workflow-operator` | [.licenserc.yaml](.licenserc.yaml); [project/AddMetaInfLicenseFiles.scala](project/AddMetaInfLicenseFiles.scala) |
-| Local single-node / k8s deploy | [single-node](bin/single-node/README.md), [k8s](bin/k8s/README.md) |
+| Run the local dev stack (infra in Docker; backend/frontend/agent-service native) | [bin/local-dev.sh](bin/local-dev/README.md) |
+| Single-node / k8s deploy | [single-node](bin/single-node/README.md), [k8s](bin/k8s/README.md) |
 
 If a topic is above, **read that file** instead of asking here.
 
@@ -62,6 +63,13 @@ Reset to `upstream/main` at start; `git log upstream/main..HEAD` should
 contain only this PR's commits before pushing; remove the worktree after
 merge.
 
+Prefer [`bin/local-dev.sh`](bin/local-dev/README.md) to run the stack while
+developing. Its native services bind fixed ports and share one PID/state dir,
+so only one worktree's stack runs at a time: `bin/local-dev.sh down` in the
+old worktree before switching, then `up` in the new one. Use the
+non-interactive CLI subcommands (`up` / `down` / `status` / `logs`); the
+interactive TUI (`-i`) is for humans, not agents.
+
 ### Environment
 
 | Component | Version |