docs: standardize repository decisions and change records

.agents/skills/create-pr/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: create-pr
+description: Prepare or update a pull request with focused validation, current ADRs, and a complete PR update record.
+---
+
+# Create or update a pull request
+
+## Repository documentation requirements
+
+Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update
+ADRs for resolved durable decisions, keep affected README/setup/public docs current,
+and maintain the complete pending or PR-numbered update record after every revision.
+Use the shared templates and section names. Missing or stale required documentation
+blocks completion. Document already authorized decisions without asking again; ask
+only about unresolved choices. These requirements govern documentation instructions
+elsewhere in this skill; preserve its repository-specific implementation and checks.
+
+Inspect the actual base branch, current diff, existing PR, and unrelated workspace
+changes. Complete authorized implementation and focused repository checks before
+publishing. Follow `pre-commit-checks` and `maintain-docs`; include affected ADRs,
+README/setup/public docs, and the pending update record in the reviewed diff.
+
+When publishing is authorized, intentionally stage the task files, commit, push,
+and open or update a draft PR. Read its actual number/URL, rename the pending record
+to `docs/updates/<number>.md`, update its contents, and push it to the same PR. Link
+that record and relevant ADRs/related PRs in the description. Recheck the full diff,
+validation, and documentation after later review or rebase changes. Never include
+unrelated work, secret values, or unverified claims. Do not merge unless authorized.

.agents/skills/grill-with-docs/ADR-FORMAT.md

@@ -1,47 +1,5 @@
-# ADR Format
+# ADR format
 
-ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
-
-Create the `docs/adr/` directory lazily — only when the first ADR is needed.
-
-## Template
-
-```md
-# {Short title of the decision}
-
-{1-3 sentences: what's the context, what did we decide, and why.}
-```
-
-That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
-
-## Optional sections
-
-Only include these when they add genuine value. Most ADRs won't need them.
-
-- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
-- **Considered Options** — only when the rejected alternatives are worth remembering
-- **Consequences** — only when non-obvious downstream effects need to be called out
-
-## Numbering
-
-Scan `docs/adr/` for the highest existing number and increment by one.
-
-## When to offer an ADR
-
-All three of these must be true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
-
-If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
-
-### What qualifies
-
-- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
-- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
-- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
-- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
-- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
-- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
-- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.
+Use the shared [ADR convention and template](../../../docs/adrs/README.md). Read the governing
+record before changing a decision. Record already resolved decisions directly and
+append timestamped amendment history; ask only when the decision is unresolved.

.agents/skills/grill-with-docs/SKILL.md

@@ -43,13 +43,13 @@ If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The ma
 ├── src/
 │   ├── ordering/
 │   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
+│   │   └── docs/adrs/                 ← context-specific decisions
 │   └── billing/
 │       ├── CONTEXT.md
-│       └── docs/adr/
+│       └── docs/adrs/
 ```
 
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adrs/` exists, create it when the first ADR is needed.
 
 ## During the session
 
@@ -75,9 +75,9 @@ When a term is resolved, update `CONTEXT.md` right there. Don't batch these up 
 
 `CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
 
-### Offer ADRs sparingly
+### Record durable decisions
 
-Only offer to create an ADR when all three are true:
+Create or update an ADR when a resolved decision carries durable reasoning. Strong signals include:
 
 1. **Hard to reverse** — the cost of changing your mind later is meaningful
 2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
@@ -86,3 +86,13 @@ Only offer to create an ADR when all three are true:
 If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
 
 </supporting-info>
+
+## Repository documentation requirements
+
+Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update
+ADRs for resolved durable decisions, keep affected README/setup/public docs current,
+and maintain the complete pending or PR-numbered update record after every revision.
+Use the shared templates and section names. Missing or stale required documentation
+blocks completion. Document already authorized decisions without asking again; ask
+only about unresolved choices. These requirements govern documentation instructions
+elsewhere in this skill; preserve its repository-specific implementation and checks.

.agents/skills/improve-codebase-architecture/SKILL.md

@@ -1,10 +1,20 @@
 ---
 name: improve-codebase-architecture
-description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adrs/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
 ---
 
 # Improve Codebase Architecture
 
+## Repository documentation requirements
+
+Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update
+ADRs for resolved durable decisions, keep affected README/setup/public docs current,
+and maintain the complete pending or PR-numbered update record after every revision.
+Use the shared templates and section names. Missing or stale required documentation
+blocks completion. Document already authorized decisions without asking again; ask
+only about unresolved choices. These requirements govern documentation instructions
+elsewhere in this skill; preserve its repository-specific implementation and checks.
+
 Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
 
 ## Glossary
@@ -67,5 +77,5 @@ Side effects happen inline as decisions crystallize:
 
 - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
-- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md).
+- **A candidate is rejected for a durable reason:** record the resolved decision and rationale in the governing ADR so later work does not repeat the same proposal. Skip ephemeral reasons and self-evident implementation choices. Ask only when the underlying decision is unresolved.
 - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

.agents/skills/maintain-docs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: maintain-docs
+description: Maintain repository ADRs, change and PR update records, and affected setup/public docs while implementing or reviewing changes.
+---
+
+# Maintain repository documentation
+
+Follow [docs/README.md](../../../docs/README.md), the shared documentation contract.
+Read governing ADRs before implementation. Write accepted durable decisions in
+`docs/adrs/`; amend current text and append timestamped history when they change.
+Record already authorized decisions directly and ask only about unresolved choices.
+
+Keep one complete update record using [the template](../../../docs/updates/template.md).
+Before a PR exists, use `docs/updates/pending/<short-slug>.md`. After the authorized
+PR is opened, rename it to `docs/updates/<actual-pr-number>.md` using the verified
+number and URL. Refresh it after each revision; never invent a number or publish
+solely to obtain one.
+
+Review affected READMEs, setup/deployment instructions, generated contracts, and
+public documentation. Update them in the same change, linking related repository
+records and deployment order when applicable. Before handoff, compare the docs with
+the complete final diff and report actual validation and remaining work. Missing
+or stale required documentation blocks completion. Release notes remain separate.

.agents/skills/pre-commit-checks/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: pre-commit-checks
+description: Validate the affected diff and required documentation before committing or completing a pull request.
+---
+
+# Pre-commit checks
+
+## Repository documentation requirements
+
+Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update
+ADRs for resolved durable decisions, keep affected README/setup/public docs current,
+and maintain the complete pending or PR-numbered update record after every revision.
+Use the shared templates and section names. Missing or stale required documentation
+blocks completion. Document already authorized decisions without asking again; ask
+only about unresolved choices. These requirements govern documentation instructions
+elsewhere in this skill; preserve its repository-specific implementation and checks.
+
+Inspect the complete task diff and preserve unrelated changes. Read the repository
+instructions and run checks appropriate to the affected components. Fix in-scope
+failures and distinguish pre-existing failures and unavailable external checks.
+
+Follow `maintain-docs` before handoff: review governing ADRs, update durable decisions,
+keep affected README/setup/public docs accurate, and refresh the current update
+record. A missing or stale required record blocks completion. Check formatting,
+links, generated artifacts, release-note obligations, and the final diff. Report
+only checks actually run; do not publish or merge without existing authorization.

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+# Summary
+
+Describe the problem and resulting behavior.
+
+# Validation
+
+List focused checks actually run and any remaining work.
+
+## Documentation
+
+- Link the current `docs/updates/<actual-pr-number>.md` record (rename the pending record after PR creation).
+- Link new or amended ADRs under `docs/adrs/`, or state `ADR review: no new decision` with a reason.
+- List affected README, setup/deployment, and public documentation changes; link related repository PRs and merge order.
+- Confirm the update record describes the full current diff, actual validation, and required consumer/operator actions.
+- Refresh this section and the same update record after subsequent review or rebase changes.

.gitmodules

@@ -1,5 +1,5 @@
 [submodule "docs"]
-	path = docs
+	path = public-docs
 	url = https://github.com/trytilde/docs
 [submodule "harness-shop"]
 	path = harness-shop

AGENTS.md

@@ -21,7 +21,7 @@ CLI Factory is an agent-first Go CLI for discovering and invoking curated SaaS/t
 - Root `secrets.yaml` is plaintext and gitignored. Use `make sops-encrypt` / `make sops-decrypt` to manage `secrets.enc.yaml` and `.env.secrets`.
 - `OPENAI_API_KEY` for `make generate-catalog` can come from `.env.secrets`.
 - Catalogue embeddings are embedded as `catalog/embeddings.bin`, a compact float32 binary index. The JSON file is only the manifest.
-- Human docs are generated into the `docs/` git submodule, which points at the shared `trytilde/docs` Mintlify repo. `make generate-docs` initializes the submodule before writing generated pages.
+- Human docs are generated into the `public-docs/` git submodule, which points at the shared `trytilde/docs` Mintlify repo. `make generate-docs` initializes the submodule before writing generated pages.
 
 ## Required Checks
 
@@ -34,3 +34,14 @@ make build
 ```
 
 Use `make build-all` before release-sensitive changes.
+
+## Required documentation maintenance
+
+For every change, follow [docs/README.md](docs/README.md). Read relevant
+`docs/adrs/` first; create or update records for durable decisions and keep setup,
+README, and public documentation in sync. Maintain the complete change record at
+`docs/updates/pending/<short-slug>.md` until a PR number exists, then rename it to
+`docs/updates/<actual-pr-number>.md` and refresh it after every revision. Missing
+or stale required documentation blocks completion. Record already authorized
+decisions directly; ask only about unresolved choices. See
+[maintain-docs](.agents/skills/maintain-docs/SKILL.md) for the workflow.

Makefile

@@ -4,7 +4,7 @@ export BASH_ENV := $(HOME)/.bashrc
 SOPS_KMS_ARN ?= arn:aws:kms:us-east-1:914788356809:alias/tilde-app-dev-sops
 CATALOG_EMBEDDING_MODEL ?= text-embedding-3-small
 CATALOG_EMBEDDING_DIMENSIONS ?= 768
-DOCS_REPO_DIR ?= docs
+DOCS_REPO_DIR ?= public-docs
 
 .PHONY: test test-unit test-e2e test-provider test-provider-tool ensure-docs-submodule generate-metadata generate-docs generate-catalog generate-catalog-provider generate-catalog-tool build build-all sops-encrypt sops-decrypt env-secrets sops-encrypt-provider-test-secrets help
 
@@ -29,7 +29,7 @@ test-provider-tool: generate-metadata ## Run e2e tests for one tool: make test-p
 	go test ./providers/$(PROVIDER)/$(TOOL) -run TestE2E
 
 ensure-docs-submodule: ## Ensure shared docs git submodule is initialized
-	git submodule update --init --recursive docs
+	git submodule update --init --recursive public-docs
 
 generate-metadata: ## Generate static Go metadata/schema files from provider YAML
 	go run ./tools/generatemetadata

README.md

@@ -171,3 +171,21 @@ The harness secrets form writes `providers/<provider>/override_test_secrets.yaml
 CLI Factory is intended to become a shared catalogue of high-quality agent tools. If you want agents to use your SaaS product well, contribute a provider with a small set of thoughtful commands and real e2e tests.
 
 Star the project, open issues or PRs, and join the Tilde community on [Discord](https://discord.gg/jj7sNyCGD4).
+
+## Documentation locations
+
+Repository decisions and change records live in [docs/](docs/README.md). Shared
+Mintlify pages are generated into the independent `public-docs/` submodule.
+`DOCS_REPO_DIR` can select a different checkout of the shared documentation.
+
+When updating an existing checkout that still uses the old `docs/` submodule,
+commit or back up any submodule changes first, then run `git submodule deinit docs`
+**before** switching to this revision. Do not force deinitialization past local
+changes. After updating the branch, run `git submodule sync` and
+`git submodule update --init --recursive public-docs`; `make generate-docs`
+initializes the new location as needed. Fresh clones only need the latter update.
+
+If an existing checkout was updated before deinitialization, the old submodule may
+leave a stale `docs/.git` and shared-documentation files behind. Preserve that
+checkout's changes before cleaning up the old files. Do not remove the entire
+`docs/` directory: it now contains tracked repository records.