[#119] Add AI agent guide and refresh user entry points#123
Open
SkowronskiAndrew wants to merge 2 commits into
Open
[#119] Add AI agent guide and refresh user entry points#123SkowronskiAndrew wants to merge 2 commits into
SkowronskiAndrew wants to merge 2 commits into
Conversation
- New Documentation/agent-guide.md: recommended workflow for AI agents analyzing a build (analyze -> query views -> drill down), the id vs object_id distinction, one-build-per-database, TypeTree requirements, the refs table, and a worked diagnose-a-bundle example. Linked from README, unitydatatool.md, AGENTS.md, and it replaces the pre-agent-era "Using AI tools" section of analyze-examples.md. - The --help documentation URL now pins to the release tag when the version has no pre-release suffix; main carries a -dev suffix and keeps linking to the docs on main. - README Downloads section points at GitHub Releases instead of the Actions tab.
We don't need to recommend binary2text --hexfloat now that it is available in the dump command directly.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves first-contact entry points for UnityDataTool users (including AI agents) by adding an agent-oriented workflow guide, refreshing discovery links, and making --help link to version-appropriate documentation.
Changes:
- Added
Documentation/agent-guide.mdand linked it from key entry points (README, unitydatatool.md, AGENTS.md, analyze-examples.md). - Updated README downloads guidance to point to GitHub Releases instead of Actions.
- Updated
--helpoutput to link docs toblob/vX.Y.Z/...for release builds andblob/main/...for dev builds, supported by a-devInformationalVersion convention.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| UnityDataTool/UnityDataTool.csproj | Adds -dev suffix guidance for InformationalVersion to support versioned doc links. |
| UnityDataTool/Program.cs | Builds documentation URL dynamically based on InformationalVersion (release tag vs main). |
| README.md | Adds link to the new agent guide; updates Downloads section to point to Releases. |
| Documentation/unitydatatool.md | Links to the new agent guide from the docs hub table. |
| Documentation/comparing-builds.md | Updates “Special cases” text; currently contains an invalid dump --hexfloat reference. |
| Documentation/analyze-examples.md | Replaces outdated “AI tools” section with a pointer to the new agent guide. |
| Documentation/agent-guide.md | New usage-oriented workflow guide for AI agents and scripting against the analyze DB. |
| AGENTS.md | Adds a short routing note pointing tool users to the agent guide. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+329
to
+330
| * This can happen if the change happens in the header of the file, or in some padding bytes. Such cases are rare because the Serialized File format is quite stable, but is a possibility if comparing files produced by different versions of Unity. | ||
| * Sometimes float or double values might appear to be identical in the decimal text representation, but there could be a difference in the actual binary representation. Specify the `--hexfloat` argument to dump to address this issue. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #119.
A review of how well AI agents can use UnityDataTool unattended found that the tool itself and the documentation hold up well, but the entry points have gaps: the
--helpdocumentation link always points at main (wrong docs for old binaries), the README still directs downloads to the Actions tab even though Releases exist, the "Using AI tools" example predates AI agents, and there is no usage-oriented starting page — experiments with a mid-tier agent showed the same few facts (the two id columns, one build per database, TypeTree requirements, therefsschema) being re-derived by trial and error.Changes
Documentation
Documentation/agent-guide.md: the recommended workflow for AI agents (and scripts) analyzing a build — analyze into a database, start from the views, drill down withdump/serialized-file/archive, trace withfind-refs— plus the facts that cost the most discovery time (idvsobject_id, one build per database, TypeTrees, therefstable) and a worked "diagnose a bundle" example.unitydatatool.md, and a short routing note at the top ofAGENTS.md(which stays contributor-focused). The pre-agent-era "Using AI tools to help write queries" section ofanalyze-examples.mdnow points to the guide.Versioned documentation link in --help
--helpoutput now pins to the matchingvX.Y.Ztag when the version is a bare release number, and links to main otherwise.InformationalVersionon main now carries a-devsuffix (2.2.0-dev). Release flow gains one small step, documented next to the property in the csproj: drop the suffix before tagging, then bump to the next-devversion.Testing
dotnet build -c Releaseclean; fullUnityDataTool.Testssuite green (286 passed).Version: 2.2.0-devand links toblob/main/...; a build with-p:InformationalVersion=9.9.9links toblob/v9.9.9/....