Prepare public CoCo 3 documentation and portable VCC Plus workflow

This commit is contained in:
Brian Holman committed 2026-11-11 16:43:19 -07:00
1 parent e9574b6f0d
commit 4aa739780c
16 files changed
+572 -913

No files matched your search

+81 -82
View File
@@ -1,98 +1,97 @@
# MCP kickoff and connection inventory
# Connect this project through MCP
Verified November 10, 2026 against installed official VCC Plus **3.5.5 (48)**.
Keep private grant files and tokens outside Git. This is a connection record,
not permission to inspect emulator implementation or another game's project.
VCC Plus shares a selected project through its supported local Model Context
Protocol connection. Use the official downloaded app, this checkout and your own
connection. Create a scoped connection for the project you selected and verify
its current identity before building or testing.
| Connection | Live tools used | Verification |
## Prepare the C-project connection
1. Open this existing game project in **Develop → C Development…** and select
**Release**. Check that `main.c`, the supplied Makefile and project resources
belong to this checkout.
2. In **Assistant…**, review the files and permissions to share. Select **Use
Project Makefile** for its declared recipe. Select **Allow Disposable
Playtests** only when you want the assistant to run isolated copies of the disk.
3. Save a fresh private connection and add it to ChatGPT through the supported
workflow described by the installed manuals. Keep VCC Plus and the shared
workspace open while using it.
4. Discover the tools currently exposed. Make a real project/capabilities request
before changing files or building. Verify project identity, revision, input
files, recipe, Release configuration and the declared disk action.
A configured server, a displayed tool list and successful project access are
three different checks. Tool discovery alone does not establish that the editor
is still open or the connection still authorizes its current project.
## Check three kinds of access separately
| Access | What to verify | What it is for |
| --- | --- | --- |
| Quadrapassel C project | `get_capabilities`, `read_project_inputs`, `refresh_project`, `build_project`, `get_build`, owned-playtest tools | Project `A1AFAA7E-C427-4437-8D1C-EB68D8C225EF`; this repository's root Makefile, files and hashes |
| Installed manuals/API (through the C connection) | `search_help`, `read_topic` | Read HSCREEN/HSET, keyboard, joystick, timer, SOUND, beep and PCLEAR topics |
| Archive Library (separate connection) | `search_archive`, `get_archive_citation` | Both succeeded; found Tandy's Color Computer 3 Extended Basic, PDF pages 152–153 |
| C project | The intended project and current source/build identity | Read/edit proposals, declared Make builds and any approved owned tests |
| Manual Library | A real search followed by reading a returned topic | Installed CMOC API contracts and VCC Plus usage guidance |
| Archive Library | Its own read-only connection and a successful search/citation | Historical CoCo manuals, publications and hardware references |
At this chat's start no VCC Plus tools appeared in its tool catalog. Connections
were exported through the installed app's normal native interface. Its public
manual, `vibe-coding-with-chatgpt/01-first-connection.html`, explicitly permits
ordinary STDIO MCP through `/Applications/VCC Plus.app/Contents/Helpers/vcc-mcp`
with the two arguments `--grant` and the private grant filename. The unmodified
installed helper is used by a small MCP client; no alternative server, private
bridge or integration endpoint is used.
Project connections include manual access; Archive Search has its own connection
exported from the Archive Library panel. Do not infer that Archive access is
missing just because it is absent from a C connection's tool list. Keep a
publication/page citation when using an archived source.
Archive Library has its own link button and **Save Archive Search Connection…**
flow. Brian explicitly approved this connection on November 10. Its advertised
build-48 tools return citations/locations, rather than full page text. Use the
Archive Library native reader for the original page when needed. Do not infer
that Archive MCP is unavailable from the C connection's tool inventory.
Common public project tools include `get_capabilities`, `read_project_inputs`,
`refresh_project`, `build_project` and `get_build`; owned-run and capture tools
are present only for supported, granted capabilities. Manual and Archive tools
have their own returned schemas. These names are discovery examples, not an
instruction to assume a tool exists or hardcode its arguments.
For future kickoff checks, distinguish **configured**, **tools discovered**, and
**successful request**. Inventory each required connection separately before
implementation or web fallback. Confirm the intended project and current revision
before builds. Connection identity and advertised tools may change after a new
export; discover them again, rather than inventing tool names or endpoints.
## Build and test the selected revision
Example verified Archive reference:
Ask the assistant to identify what it can actually do, then:
- Title: *Color Computer 3 Extended Basic (Tandy)*.
- Citation: `sha256:26d4ca51f3477263f3e85269091104079ae88ad83c842cef0e3bc531324e7f5e:pdf_page:152`.
- Read in Archive Library: printed page 143, “Adding Pages (The PCLEAR Command)”.
It describes the default four PMODE pages and reserving fewer pages.
1. Review or refresh changed project inputs through the supported native flow.
Keep the ordinary helper connected while a review is awaiting a decision.
2. Build the current revision's declared **Release** disk action. Poll the build
result, inspect diagnostics/memory bounds and retain the artifact identity.
3. Start an approved disposable run from that exact artifact. Poll startup and
check its actual RAM/CPU/disk configuration before making a test claim.
4. Apply ordinary guest input with release intervals, inspect real frames and
save behavior, and capture bounded audio when available. Stop the owned run
and retain its disk receipt when finished.
Initial hardware-reference web lookups occurred before discovering the separate
Archive connection. That was a discovery error, not a demonstrated Archive gap.
Brian asked that the kickoff feedback be sent to **Deploy VCC Plus Gitea**; the
approved concise feedback was delivered there. No emulator update is requested.
Do not copy mutation request IDs from older runs, use another project's grant,
or assume a past screenshot came from the current build. Keep observations bound
to the project revision, build/artifact and test configuration.
## November 11 reconnection
## If access stops working
Brian approved installed official VCC Plus 3.6.0 (51) and an idle desktop window.
The same repository was opened through C Development and its private project
connection renewed outside Git. A successful `get_capabilities` returned project
`84772EFC-B651-4A98-B09E-932247575EA7`, session
`185C8449-CB9B-4A38-81C8-D43CDA4A3ABE`, app build 51, approved Make recipe,
and the expected Quadrapassel files. This connection still advertises fixed
512 KB disposable workers, MC6809/HD6309, graphics and audio captures.
Archive access is separate and was not needed for this local font adaptation.
Check whether the app and the intended C workspace remain open, whether sharing
is enabled for that project, and whether the private export is still current.
Changing projects, closing the shared workspace, revoking access or exporting a
replacement connection can end an earlier connection. Reconnect through the
native panel and repeat discovery instead of guessing a private endpoint.
After Brian's November 11 restart, the old private grant expired. The same
project connection was renewed through the supported interface. Current project
`3D6A502C-E06D-46BC-9D19-191D741A16B9`, revision 2, built and ran successfully
on official build 51. get_machine_status read normal-session configuration;
no writable disks or peripherals were removed to satisfy native-run blockers.
The new candidate used only disposable playtests.
A tool list can be available while a live request fails. If the environment blocks
access to the app's local service, check the supported connection and applicable
local app/service permission. An actual permission block is different from a
missing tool. Report the observed error; do not replace the app or weaken system
security to hide it. Continue source/documentation work that does not need the
connection until access is restored.
Brian approved official VCC Plus 3.6.1 (53) and an idle desktop window for the
joystick investigation. The renewed connection verified project
7D6E1D9C-DF7C-4B15-B64D-6B30732417CB, revision 2, built successfully and ran the
frozen artifact. Its playtest_input schema still supports only keyboard keys,
not analog axes/fire injection. No native joystick pass is inferred from it.
Capabilities vary between public app releases. If joystick injection, a CPU/RAM
choice, graphics inspection or audio capture is absent, use the supported native
workflow or a clearly identified user-controlled test for that part. Never treat
keyboard input as analog joystick evidence or a worker's 512 KB configuration as
an additional 128 KB test.
Build 03 used that project at revision 3 on official build 53. Keep the official
STDIO helper connected while a refresh awaits native review: with the one-shot
helper disconnected the review window was not presented. Closing C Development
invalidated this private grant after all owned runs stopped. Reconnect through
the official interface when more MCP work is needed.
## Keep sharing private and scoped
Only real result folders belong in outputDirectories. An attempt to exclude
numbered DSK files there was accepted by MCP inventory but broke native project
opening (reported as missing assets/ui-text.tsv). File exclusions were removed;
explicit resourceInputs names the two real text inputs. Native project loading
and Release disk build then passed. Root delivery disks remain project resources:
freeze them during owned tests and create/update delivery filenames after the run
stops. Personal media/backups are never reset to satisfy source identity.
Keep connection exports, tokens and credentials outside the repository and out of
chat text. Do not add them to commits, screenshots, public issues or manuals.
Use only the ordinary official helper/client procedure in the installed manual;
no replacement server, private endpoint or emulator-source inspection is needed.
Revoke a connection when its work is finished, and preserve writable test disks
and personal media independently of the connection's lifetime.
Build04 was built and qualified through the native installed build53 C Development
workflow after the grant ended. Native builds FC462D93 / A7A18927 succeeded.
Launch Disk mounted a separate working copy; explicit cold restart plus DOS was
required because the prior graphics game was still in RAM. A new mounted filename
or C workspace's latest-build badge alone does not prove the guest reloaded it.
Build05 final checks use official build54's newly exported native connection,
project273E195B-8BFC-495F-A1F8-E1469759B910 revision0. Discovery returned29 tools,
playtest_joystick_input and input_diagnostics; actual standard port/axis/fire2
steps and get_playtest_input were used successfully. The official local helper
required local-service execution permission; without that permission it returned
host_unavailable despite local tools/list succeeding. This was resolved without
replacing the grant or changing the emulator. All owned runs stopped; the native
workspace was released to Core for the next project's scoped connection. Private
grant files remain outside Git. See SECONDARY_BUTTON.md for exact evidence.
The public [connection lesson](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/01-first-connection/)
and [existing C-project example](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/06-capitals/)
provide the supported user-facing setup steps. For the game-specific build and
media rules, use [VCC_PLUS_WORKFLOW.md](VCC_PLUS_WORKFLOW.md).