Document ALL (or ... more, rather) of the things!

[georgestephanis]

Add some Antigravity-generated documentation to the repository to make it a bit easier for agents and humans to onboard and parse through it.

Intended to address https://meta.trac.wordpress.org/ticket/8367

AI Disclosure: I worked with Antigravity-IDE to generate most of this documentation, and expect it will be further refined moving forward.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props georgestephanis, obenland.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[obenland]

Thanks @georgestephanis! I pushed a few changes and clarifications on things that I noticed.

I'm in favor of having an AGENTS.md (and claude equivalent), so I'm glad that's part of the PR. The details I'm a bit more skeptical of, like all three items in the "Architectural Patterns & Conventions" section. Why the focus on these three, which seem pretty specific and not really reflecting patterns? "Deep-Dive Integrations & Internals", is that something agents need to know about in every session? Things of that nature.

For the READMEs: I think the ones in the repo root and in .github/ are useful and worth iterating on and giving them more meat.
The three subdirectory READMEs (api.wordpress.org, common, wordpress.org) are where I'm less sure. A lot of the content restates what the directory names already tell you ("photo-directory powers the photos registry") and I worry that they'll just get outdated quickly since they mostly just recount the directories. Maybe we could just drop those. Curious what you think?

[georgestephanis]

I'm personally in favor of the subdirectory readmes, as I've found when navigating the repository it can be nice to have that context loading up automagically as you navigate -- like when clicking around in https://github.com/WordPress/gutenberg/tree/trunk/packages for example (which is the first repo that kinda got me on the pattern of it).

[obenland]

I'd agree if they'd provide context and non-obvious information, like in your example, but at the moment they're mostly just listing files and directories.

[georgestephanis]

My big want is to get something in. If you'd rather do a thinner addition, I'm fine dropping stuff -- you have a lot more experience than I do in this repo.

[obenland]

Sounds good! Let's drop the readme's in api.wordpress.org, common, and wordpress.org for now and get the rest in as a first pass