[#119] Add AI agent guide and refresh user entry points - #123
Merged
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.
…perimental - agent-guide.md: drop find-refs from the core loop; new 'Tracing why content is in the build' section walks refs_view directly with the per-build-type endpoints (assetbundle_assets, ContentLayout loadables, Player file naming). Split the worked example into a full-build diagnosis (where view_potential_duplicates is meaningful) and a single-bundle-in-isolation example. - Mark find-refs experimental in the CLI help, command-find-refs.md (with a pointer to #121), and the README library list.
The Version property was stuck at 2.0.0 and unused: AssemblyVersion, FileVersion and InformationalVersion are all set explicitly, so it only invited confusion when editing versions for a release.
view_potential_duplicates is only expected to have results for AssetBundle builds, and 'AssetBundle' is spelled out instead of the overloaded 'bundle' shorthand.
Pushing a vX.Y.Z tag now produces its own Build run, so the release artifacts come from a run unambiguously tied to the tagged commit instead of having to pick the right push-triggered main run.
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
New
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.Linked the guide from the README documentation table,
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.README "Downloads" section points at the Releases page instead of the Actions tab (which no longer publishes binaries).
Marked
find-refsas experimental (CLI help,command-find-refs.mdwith a pointer to find-refs: clarify reference semantics — docs, output/error behavior, and tests #121, README) and steered the agent guide to directrefs_viewqueries with per-build-type endpoints instead, until find-refs: clarify reference semantics — docs, output/error behavior, and tests #121 is addressed.The worked example analyzes the full build (where
view_potential_duplicatesis meaningful), with a second example for analyzing a single AssetBundle in isolation.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.Release flow cleanup
v*tag pushes, so release artifacts come from a run unambiguously tied to the tagged commit (main runs build the-devversion).<Version>2.0.0</Version>csproj property that invited confusion when editing versions for a release.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/....