Claude Code cloud sessions can't run Vale (Docker unavailable, binary install blocked) and yarn lint leaves jsconfig.json dirty

[jstirnaman]

Summary

While working a content PR (#7469) from a Claude Code on-the-web / remote
sandbox session, I hit two recurring friction points worth fixing so future
agent (and human sandbox/devcontainer) sessions don't have to work around
them:

1. Vale can't run in this class of session — neither of its two
   supported execution paths works, forcing every commit to use
   --no-verify and skip style linting entirely.
2. yarn lint leaves assets/jsconfig.json modified as an apparent
   side effect, adding unrelated noise to otherwise-scoped diffs.

1. Vale is unusable in Docker-less, GitHub-egress-restricted sessions

.ci/vale/vale.sh supports two run modes:

• Local binary (preferred, per the vale-linting skill and the script
  itself)
• Docker fallback (jdkato/vale:v3.15.1)

Both are unavailable in this session type:

• Docker fallback: no Docker daemon running in the sandbox
  (failed to connect to the docker API at unix:///var/run/docker.sock).
• Local binary install: the CI-documented install command —

  curl -sfL "https://github.com/errata-ai/vale/releases/download/v3.15.1/vale_3.15.1_Linux_64-bit.tar.gz" \
    | sudo tar xz -C /usr/local/bin vale

  — returns HTTP 403 from the session's proxy:

  {"message":"GitHub access to this repository is not enabled for this session. Use add_repo to request access.","documentation_url":"..."}

  errata-ai/vale isn't (and shouldn't need to be) a repo added to a
  docs-v2 session's scope just to fetch a release binary.

Impact: core-lint, enterprise-lint, lint-instructions, and every
other product-specific Vale job in lefthook.yml fail outright in this
environment, regardless of whether the changed content has any real style
issues. The only way forward is git commit --no-verify, which skips
all pre-commit hooks for that commit, not just the Vale jobs — including
checks that would otherwise run fine and are useful (link/anchor checks
partially overlap here too, see below). PR #7469's Vale checks did pass
cleanly in real CI once pushed, confirming the content itself was fine — the
gap is purely environmental.

Suggested directions (pick whichever fits docs-v2's constraints best):

• Mirror the Vale binary to a host this proxy allows (e.g., an internal
  artifact bucket, npm registry, or one of the already-allowlisted hosts
  like registry.npmjs.org/pypi.org), so the documented local-binary
  install path works without needing errata-ai/vale in scope.
• Vendor the Vale binary (or a thin installer script fetching from an
  allowed mirror) into the repo/devcontainer setup so sandbox sessions get
  it automatically, similar to how CI installs it directly in
  pr-vale-check.yml.
• Document this specific gap (proxy-blocked GitHub release downloads +
  no Docker) in the vale-linting skill or AGENTS.md's existing
  "Network-restricted environments" note, with the recommended
  --no-verify justification spelled out, so agents don't have to
  re-derive it each time.

2. yarn lint (via lefthook) leaves assets/jsconfig.json dirty

Running yarn lint in this session consistently left an uncommitted change
to assets/jsconfig.json:

   "paths": {
    "*": [
-    "*"
+    "*",
+    "../node_modules/*"
    ]
   }

This happened twice in the same session, each time after running the full
yarn lint (pre-commit + pre-push lefthook chain) — not tied to any specific
content change, and unrelated to anything intentionally edited. I reverted it
each time with git checkout -- assets/jsconfig.json to keep the commit
scoped, but didn't track down the exact script/tool responsible (candidates
worth checking: build:ts/tsc --project tsconfig.json, or some
IDE/language-server-style tool invoked transitively during
validate-agent-instructions or packages-audit).

Impact: minor, but it's silent noise that a less careful commit could
pick up unintentionally (git add -A-style staging would include it), and
it suggests some tool in the lint/build chain treats jsconfig.json as a
generated file without that being documented anywhere.

Suggested directions:

• If jsconfig.json's paths entry is meant to be regenerated
  automatically, document that (e.g., a comment in the file, or a note in
  assets/AGENTS.md) and consider gitignoring the generated portion or
  committing the "correct" post-generation state so it stops diffing.
  • If it's not meant to be touched by tooling at all, find and fix
    whatever step is writing to it (likely something invoked via yarn lint
    or yarn build:ts) — happy to help track it down further if useful,
    I just didn't want to block the PR this surfaced on chasing it down.

Context

Both surfaced while working PR
#7469 (InfluxDB 3
canonical frontmatter fix) from a Claude Code remote/cloud session — not
specific to that PR's content, but to the session environment itself.

[jstirnaman]

Vale tooling evaluation (Problem 1 only)

Investigated the Vale execution failure in sandboxed agent sessions, reviewed all Vale configs/overrides, and evaluated whether Vale is worth keeping versus replacing with other tools + custom scripts + an AI style-review agent. All network claims below were verified empirically from inside an affected sandbox session.

Findings

The failure is environmental, not a Vale defect.

• GitHub release downloads return 403 through the session proxy.
• The Docker CLI is present but the daemon is not running, so the jdkato/vale fallback can't work.
• install.vale.sh is also unreachable.
• CI (pr-vale-check.yml) is unaffected and remains the authoritative gate.

The npm-packaged binary (@vvago/vale) is not a fix.

• Its publish history confirms the lag concern: 3.12.0 (Jun 2025) → 3.14.2 (May 2026), skipping 3.13.x–3.14.1.
• Unpacking the current 3.15.1 tarball shows it's a ~5 KB postinstall script that downloads the binary from github.com/errata-ai/vale/releases — the same blocked URL — so it would fail in sandboxes even when current. PyPI's vale package is stale (3.13.0.0) with the same pattern.

Version currency and project health are fine.

• The repo's pin (3.15.1) is the latest upstream release — no current security lag, because CI installs directly from GitHub releases rather than a repackaged channel.
• Vale is actively maintained; the org renamed errata-ai → vale-cli (the CI download URL still worked via redirect).

Config review: 7 .vale.ini files, 6 custom style packages, 13 custom rules, ~700 lines of vocabulary — all functioning. Two observations:

• lefthook.yml's clustered-lint pointed at the cloud-serverless config instead of the existing content/influxdb3/clustered/.vale.ini (copy-paste error).
• The only error-level (blocking) rules are InfluxDataDocs.DateFormat plus ~14 mechanical Google rules; Branding/v3Schema are warning-level (advisory). Left as-is intentionally — promoting them would need a false-positive audit first.
• Inline <!-- vale --> overrides are light (14 files); healthy usage.

Recommendation: keep Vale

• The pain point is a ~10-line distribution/fallback issue, not the tool.
• Replacing Vale means reimplementing markup-aware scoping (code blocks, frontmatter, Hugo shortcodes via TokenIgnores/BlockIgnores) in custom scripts — the hard part Vale already handles — plus porting 13 custom rules and the Google style package.
• An AI style agent is a complement, not a replacement: it's non-deterministic and can't serve as a reproducible required check, but it covers judgment-level style that regex can't (doc-review-agent already fills this role).

Implemented on claude/vale-tooling-evaluation-qsvlc1 (e42fbe3)

• .ci/vale/vale.sh checks for a running Docker daemon and, when neither a v3+ binary nor a daemon is available, warns and exits 0 so the remaining pre-commit hooks still run — eliminating the --no-verify workaround. VALE_STRICT=1 turns the skip into a failure.
• pr-vale-check.yml sets VALE_STRICT=1 (CI can never skip silently) and downloads from the renamed vale-cli org.
• lefthook.yml clustered-lint now uses the clustered config.
• The sandbox limitation and skip behavior are documented in the vale-linting skill and DOCS-TESTING.md, including the environment-level alternative of allowlisting github.com/vale-cli/vale in the session network policy.

Verified in an affected sandbox: direct invocation skips with a warning (exit 0), VALE_STRICT=1 fails (exit 1), and a real commit ran all other hooks normally.

---

Generated by Claude Code