mirror of
https://github.com/Significant-Gravitas/AutoGPT.git
synced 2026-11-09 17:53:56 -10:00
Nicholas Tindleandunknown
f3e05a73e1
### Why / What / How
**Why:** `docs/platform/` is published at agpt.co/docs, and a page goes
live once `SUMMARY.md` lists it. Engineering notes were kept in the same
folder, so one line in `SUMMARY.md` was all that separated them from the
public site. Two of them, the activation metrics contract and the
PostHog tracking plan, had already been added to the navigation under
"Using the Platform". They are not live only because the site is built
from the `gitbook` branch, which is behind `dev`. Agents also had no
stated place to put a note that isn't a page for the site, so
`docs/platform/` was the default.
**What:** Engineering notes get their own folder, `docs/engineering/`,
which no GitBook space reads. The eleven files in `docs/platform/` that
are not pages for the site move there, the two analytics pages leave the
navigation, and the agent guides say where a document goes. A test
requires every file in `docs/platform/` to be listed in its
`SUMMARY.md`.
**How:** The files are moved with `git mv`, so history follows them.
References to the old paths are updated: five code comments, the backend
agent guide, and one link on a published page. The test lives in
`.github/workflows/scripts/`, where the PR status checker already runs
every `test_*.py` on each pull request and merge group, so it needs no
new workflow.
### Changes 🏗️
- **Moved to `docs/engineering/`** (content unchanged apart from two
relative links in `hosted-mcp-catalog.md`):
- `activation-metrics.md`, `tracking-plan.md` (both were in
`SUMMARY.md`)
- `feature-flags.md`, `org-feature-map.md`,
`workspace-media-architecture.md`, `codex-subscription-preview.md`
- `releases/clay-rock-v1.md`, `releases/clay-rock-v2.1.md`
- `contributing/hosted-mcp-catalog.md`,
`contributing/oauth-integration-flow.md`, `contributing/tests.md` (now
at the top of `docs/engineering/`)
- **`docs/platform/SUMMARY.md`**: removed "Activation Metrics &
Experiments" and "PostHog Tracking Plan".
- **`docs/platform/integrations-and-credentials.md`**: the "Maintaining
MCP Integrations" link now uses the note's GitHub URL on `dev`, because
the relative path does not exist on the docs site. It resolves as soon
as this merges.
- **Path updates**: `posthog_client.py`, `posthog_events.py`,
`product_analytics.py`, `posthog-base-properties.ts`,
`posthog-events.ts` (comments only) and
`autogpt_platform/backend/AGENTS.md`.
- **`docs/engineering/README.md`** (new): what the folder is for, that
it is not on the docs site, and that it is still public.
- **`AGENTS.md`, `docs/AGENTS.md`**: a short "where a document goes"
rule. Pages for people outside the team (using, self-hosting or
contributing) go in the published folders; the team's working documents
go in `docs/engineering/`; when unsure, `docs/engineering/`.
- **`.github/workflows/scripts/test_docs_layout.py`** (new): fails when
a Markdown file under `docs/platform/` is not listed in
`docs/platform/SUMMARY.md`, and when any published folder's `SUMMARY.md`
lists a page outside its own folder or one that does not exist. The
failure message says to move the file to `docs/engineering/` unless it
is a page meant for the site.
**What this does not do:**
- The test checks that a file is listed, not who it is written for. A
note that is added to `SUMMARY.md` still passes, so that remains a
review call.
- AutoPilot's documentation search indexes every Markdown file under
`docs/`, so it still returns these notes, as it did when they were in
`docs/platform/`. For two of them (`tests.md`,
`oauth-integration-flow.md`) the link it cites used to redirect to a
live page and now returns 404; the other nine already did. Keeping
unpublished files out of that index is a backend change for a follow-up.
- `master` still lists the two analytics pages until this change is
released. Nothing publishes from `master` today, but a docs sync from
`master` before that release would put them on the site.
No published page changes on the live site from this PR: the site is
built from the `gitbook` branch.
### Agents and large language models used
Claude Code (model: unknown)
### Checklist 📋
#### For code changes:
- [x] I have clearly listed my changes in the PR description
- [x] I have made a test plan
- [x] I have tested my changes according to the test plan:
- [x] `python -m unittest discover -s .github/workflows/scripts -p
"test_*.py"` passes (21 tests, 8 new)
- [x] The new test fails when an unlisted file is added to
`docs/platform/`
- [x] The new test fails when `docs/platform/SUMMARY.md` lists a file in
`docs/engineering/`
- [x] Every relative link in the moved files resolves, the same as
before the move
- [x] No file in the repository still references an old path
- [x] `docs/platform/` has no Markdown file left that `SUMMARY.md` does
not list
<details>
<summary>Example test plan</summary>
- [ ] Create from scratch and execute an agent with at least 3 blocks
- [ ] Import an agent from file upload, and confirm it executes
correctly
- [ ] Upload agent to marketplace
- [ ] Import an agent from marketplace and confirm it executes correctly
- [ ] Edit an agent from monitor, and confirm it executes correctly
</details>
#### For configuration changes:
- [ ] `.env.default` is updated or already compatible with my changes
- [ ] `docker-compose.yml` is updated or already compatible with my
changes
- [ ] I have included a list of my configuration changes in the PR
description (under **Changes**)
<details>
<summary>Examples of configuration changes</summary>
- Changing ports
- Adding new services that need to communicate with each other
- Secrets or environment variable changes
- New or infrastructure changes such as databases
</details>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Low Risk**
> Documentation layout, link, and comment updates plus a CI docs guard;
no application runtime, auth, or data-path changes.
>
> **Overview**
> Engineering and internal docs are split from the GitBook-published
tree by introducing **`docs/engineering/`** and moving team-only notes
(tracking plan, activation metrics, runbooks, contributing internals,
etc.) out of **`docs/platform/`**. **`docs/platform/SUMMARY.md`** drops
the two analytics pages that were one nav line away from going public,
and agent guides (**`AGENTS.md`**, **`docs/AGENTS.md`**) now spell out
published vs engineering placement.
>
> References are retargeted: PostHog-related code comments and
**`autogpt_platform/backend/AGENTS.md`** point at
**`docs/engineering/`**, and the published integrations page links to
the MCP catalog note via a **GitHub `dev` URL** because that path is not
on agpt.co/docs.
>
> **`.github/workflows/scripts/test_docs_layout.py`** enforces that
every `.md` under **`docs/platform/`** appears in
**`docs/platform/SUMMARY.md`** and that published **`SUMMARY.md`** files
only list real pages in their own folder—hooked into existing PR
**`test_*.py`** discovery in **`.github/workflows/scripts/`**.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
fb8e992a6a. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: unknown (Claude Code) <[email protected]>
875 B
875 B
Engineering notes
Working documents for the team and the agents that work on AutoGPT: analytics and tracking plans, rollout plans, runbooks, internal references, and design and architecture notes.
Nothing in this folder is on the docs site. The site at agpt.co/docs is built from docs/home/, docs/platform/ and docs/integrations/, and shows the pages listed in each folder's SUMMARY.md. A page written for people outside the team, whether they use, self-host or contribute to AutoGPT, goes there. Everything else goes here.
These notes are still public. The repository is public, and AutoPilot's documentation search indexes every Markdown file under docs/, this folder included.
- Don't list a file from this folder in a
SUMMARY.md. - To link to a note from a published page, use its GitHub URL on
dev. The relative path does not exist on the docs site.