docs: add AI context and stabilize timeout regression

.ai-context/ARCHITECTURE.md

@@ -0,0 +1,23 @@
+# Architecture
+
+Each public module is one sourceable file under `lib/bash/<module>/lib_<module>.sh`.
+`std` provides initialization, logging, checked commands, imports, filesystem
+helpers, and cleanup registration. `arg`, `str`, `list`, `file`, `git`, and `gh`
+add composable utilities. `cli` declares command models; `app` supplies typed
+configuration and application lifecycle policy. `process` offers preview
+supervision primitives rather than a second stable runner API.
+
+Sourcing stdlib is passive. Standalone consumers initialize through `base_init`;
+`bin/base-bash` preloads stdlib, initializes once, sources the application, and
+calls its `main`. Package-relative imports use `base_std_import` or the launcher's
+import helper. Public functions use `base_<module>_...`; framework-owned state
+uses `BASE_BASH_LIBS_...`. Applications retain ownership of their command and
+configuration semantics.
+
+Keep existing single-file library boundaries. Production libraries use explicit
+status checks rather than `set -e`, `set -u`, or `pipefail`. Logs belong on stderr;
+stdout remains available for command data. Release bundles, API checks, and
+consumer fixtures establish compatibility independently of any one application.
+
+Sources: [module map](../lib/bash/README.md), [stdlib contract](../lib/bash/std/README.md),
+[standards](../STANDARDS.md), and [launcher](../bin/base-bash).

.ai-context/INDEX.md

@@ -0,0 +1,11 @@
+# base-bash-libs AI context index
+
+Read in this order:
+
+1. [Project](PROJECT.md): purpose, audience, scope, and boundaries.
+2. [Architecture](ARCHITECTURE.md): components, contracts, and source map.
+3. [Workflows](WORKFLOWS.md): setup, validation, and contribution practices.
+4. [Maintenance](README.md): sources, update rules, and export behavior.
+
+The pack is curated orientation. Canonical repository sources linked from each
+page take precedence when exact implementation or policy details matter.

.ai-context/PROJECT.md

@@ -0,0 +1,21 @@
+# Base Bash
+
+`base-bash-libs` is an independently consumable Bash application framework and
+standard library. It provides checked execution, logging, cleanup, structured
+CLIs, typed configuration, and reusable shell helpers. Its consumers include
+Base, standalone scripts, and the separate Beacon reference application.
+
+Use it where Bash is an intentional runtime constraint and shared application
+infrastructure is useful. It does not require the Base workspace runtime and
+does not own an application's domain policy. Homebrew installation, vendored
+release bundles, source checkouts, and submodules are supported consumption paths.
+The documented minimum is Bash 4.2.53; macOS system Bash is insufficient.
+
+The public API manifest and versioning policy define stability. The `process`
+module is preview functionality; do not infer stable status merely because it
+ships in a release. Use VERSION and immutable release evidence for exact package
+identity instead of treating this summary as a current-release registry.
+
+Sources: [README](../README.md), [API contract](../docs/v2-api-contract.md),
+[API manifest](../base_api_manifest.yaml), and
+[support matrix](../docs/support-matrix.md).

.ai-context/README.md

@@ -0,0 +1,27 @@
+# AI context for base-bash-libs
+
+This directory is the repository's curated orientation for AI-assisted work and
+portable export. It summarizes verified repository behavior; it is not generated
+runtime evidence or an authoritative release/status registry. Start with
+[INDEX.md](INDEX.md).
+
+Keep purpose, architecture, commands, and workflows aligned with code and
+canonical documentation. Update the affected pages in the same meaningful PR;
+for typo-only or internal changes with no contract impact, record no context
+impact in the PR. Resolve disagreements by correcting this pack from its sources.
+Do not copy credentials, local databases, private machine paths, personal records,
+or transient logs into it. Link to evidence rather than copying runtime data.
+
+From this checkout, with Base available:
+
+```bash
+basectl export-context --list-files
+basectl export-context --print
+```
+
+Markdown exports combine Markdown files in INDEX order, then append unlisted
+files deterministically. Links outside this directory are source references;
+the exporter does not inline their targets. Keep core explanations self-contained.
+Use real regular files, not symlinks. Store generated bundles outside the project
+and keep generation timestamps out of source pages so unchanged exports remain
+byte-identical. This pack is picked up automatically by workspace export jobs.

.ai-context/WORKFLOWS.md

@@ -0,0 +1,27 @@
+# Workflows
+
+Start with the [v2 quickstart](../docs/v2/quickstart.md) and a verified immutable
+release when building a consumer. `base-bash check --project .` inspects a
+consumer without changing it. Library development uses the repository checks:
+
+```bash
+./tests/validate.sh
+./tests/lint-warnings.sh
+git diff --check
+```
+
+Focused BATS tests accompany behavior changes. The complete validator also
+covers API/namespace contracts, release artifacts, consumer examples, and
+compatibility. Use supported Bash and the documented development dependencies;
+run timeout/process tests with non-terminal stdin.
+
+Tracked work starts from an issue and a dedicated canonical worktree. Move its
+Project item to In Progress before implementation and In Review when the PR opens.
+Leave contributor-reserved good-first-issue work to its intended audience unless
+explicitly selected. Ordinary PRs do not change VERSION. Releases must enter
+through `scripts/release` and follow the repository's release process, including
+artifact and downstream evidence.
+
+Sources: [contribution guide](../CONTRIBUTING.md), [agent guidance](../AGENTS.md),
+[release process](../docs/release-process.md), and
+[versioning policy](../docs/versioning-policy.md).

CONTRIBUTING.md

@@ -120,3 +120,17 @@ before dispatching again; rotating a valid token is unnecessary. See the
 
 Run the offline workflow regression tests with
 `python3 tests/project-intake-test.py`; they also run in `./tests/validate.sh`.
+
+## AI Context Maintenance
+
+Start AI-assisted orientation with [.ai-context/INDEX.md](.ai-context/INDEX.md).
+Maintain these curated summaries alongside meaningful changes to product scope,
+architecture, commands, or contributor workflows. Canonical docs and code remain
+the source of truth; update the pack when they disagree. State context impact in
+the PR, including a reason when no update is needed. Typo-only and internal changes
+without behavioral or architectural impact usually need no context update.
+
+Validate changes with `basectl export-context --list-files` and
+`basectl export-context --print` from the checkout, plus `git diff --check`.
+Keep the pack self-contained enough for offline reading, free of secrets and
+private runtime data, and independent of generated timestamps or export bundles.

lib/bash/std/tests/lib_std.bats

@@ -3212,7 +3212,7 @@ EOF
 
 @test "base_std_run reports external timeout-clock failures as infrastructure without retrying" {
     local fake_bin="$TEST_TMPDIR/broken-timeout-clock"
-    local counter_file="$TEST_TMPDIR/broken-timeout-counter"
+    local clock_count_file="$TEST_TMPDIR/broken-timeout-clock-count"
     local stderr_file="$TEST_TMPDIR/broken-timeout.err"
     local rc
 
@@ -3223,28 +3223,26 @@ if [[ "${1-}" == --version ]]; then
     printf 'timeout (GNU coreutils) 9.5\n'
     exit 0
 fi
-exit 7
-EOF
-    create_script "$TEST_TMPDIR/should-not-run.sh" <<'EOF'
-#!/usr/bin/env bash
 count=0
-[[ -f "$1" ]] && count="$(cat "$1")"
-printf '%s\n' "$((count + 1))" > "$1"
-/bin/sleep 3
+[[ -f "$BASE_TEST_TIMEOUT_CLOCK_COUNT" ]] && count="$(< "$BASE_TEST_TIMEOUT_CLOCK_COUNT")"
+printf '%s\n' "$((count + 1))" > "$BASE_TEST_TIMEOUT_CLOCK_COUNT"
+exit 7
 EOF
     ln -s "$(command -v mktemp)" "$fake_bin/mktemp"
     ln -s "$(command -v rm)" "$fake_bin/rm"
 
-    if PATH="$fake_bin" base_std_run --no-exit --max-attempts 3 --timeout 1 \
-        /bin/bash "$TEST_TMPDIR/should-not-run.sh" "$counter_file" \
+    # A broken clock can stop the child before its first instruction. Count
+    # clock executions to prove no retry without depending on child scheduling.
+    if BASE_TEST_TIMEOUT_CLOCK_COUNT="$clock_count_file" PATH="$fake_bin" \
+        base_std_run --no-exit --max-attempts 3 --timeout 1 /bin/sleep 3 \
         2>"$stderr_file"; then
         rc=0
     else
         rc=$?
     fi
 
     [ "$rc" -eq 125 ]
-    [ "$(cat "$counter_file")" = "1" ]
+    [ "$(< "$clock_count_file")" = "1" ]
     [[ "$(cat "$stderr_file")" == *"could not be supervised safely"* ]]
     [[ "$(cat "$stderr_file")" != *"attempt 1 of 3; retrying"* ]]
 }