Without a token on actions/checkout, the action falls back to
GITHUB_TOKEN, which has no access to the private internal-docs
repo. Submodule clone fails with "repository not found".
PAT is back on checkout. PR ops still use GITHUB_TOKEN via the
GH_TOKEN env var on the run step. The bot-branch git push uses
the credential helper set up by checkout (the PAT, which has
Contents: Read and write).
Direct push to dev fails the dev ruleset's "Require pull request"
rule. Open a tiny PR from a bot branch and enable auto-merge
(squash, 0 approvals required) instead. No bypass actor needed —
the rule stays strict for everyone, including the bot.
PR ops use GITHUB_TOKEN with explicit pull-requests: write
permission. The cross-repo PAT is only used to rewrite the SSH
submodule URL so internal-docs can be cloned over HTTPS.
* feat(internal-docs): scaffold private docs submodule, skills, sync action
Adds the OSS-side scaffolding for the internal-docs system:
- /document-internal skill — drafts a 1-page feature/architecture/design
doc from the current branch's diff, asks four sharp questions, enforces
voice rules (no em dashes, banned filler words, 60-line cap on feature
notes), then opens a PR to browseros-ai/internal-docs via a tmp clone.
- /ask-internal skill — answers team-internal questions by greping
internal-docs and the codebase, synthesizing with file:line citations,
optionally executing surfaced commands with per-command confirmation,
and drafting a new doc + PR if grep returns nothing useful.
- .github/workflows/sync-internal-docs.yml — every 4 hours, bumps the
submodule pointer on dev directly (no PR; relies on dev branch
protection blocking force-push). Skips silently until the submodule
is configured. Uses url.insteadOf to rewrite the SSH submodule URL
to HTTPS-with-token for the bot, while keeping SSH the local default.
- .claude/skills/document-internal/seeds/ — root README and three
templates (feature-note, architecture-note, design-spec) ready to
copy into the new internal-docs repo on rollout.
Design spec: .llm/superpowers/specs/2026-04-30-internal-docs-submodule-design.md
Manual prereqs (NOT in this PR — handled out-of-band):
1. Create private repo browseros-ai/internal-docs with branch protection on main.
2. Seed it with the contents of .claude/skills/document-internal/seeds/.
3. Create a bot account, mark as bypass actor on dev branch protection.
4. Add INTERNAL_DOCS_SYNC_TOKEN secret with repo + read access to internal-docs.
5. Once internal-docs exists, on a follow-up branch:
git submodule add -b main git@github.com:browseros-ai/internal-docs.git .internal-docs
6. Send the team the one-time init snippet for their existing checkouts:
git submodule update --init .internal-docs
* fix(internal-docs): address Greptile review feedback
- Workflow: rebase onto dev before push to handle non-fast-forward race;
bump fetch-depth 1->50 so rebase has merge-base history.
- Workflow: move INTERNAL_DOCS_SYNC_TOKEN into step env: per Actions
credential-injection pattern, instead of inlining in the script body.
- Skill (BASE bug): suppress git rev-parse stdout so SHA does not get
captured into BASE alongside the literal 'dev'. Was breaking every
downstream git log/diff call.
- Skill (tmp clone): trap 'rm -rf "$TMP" EXIT after mktemp so cleanup
always runs, even if any subsequent step fails.
