Operate the authenticated Miadi Review API through the bundled client. Keep the token in the environment; never write it into this skill, a command argument, a report, or source control.
| Step | Skill | Does | Adds to the review |
|---|---|---|---|
| 1 | miadi-review |
create, import, read, version, delete; the client every step uses | the review itself |
| 2 | miadi-review-academic-fields |
correct the generated text, ground it in research | Academic Fields, Sources |
| 3 | miadi-review-internal-usage |
relate it to other reviews and to our teams and packages | Related Review, Internal Usage, Definitions |
Steps 2 and 3 exist because the point of a review is to learn what a video could change in how Miadi is built, and for whom, and the service’s generated text is too weak on its own to support that. You are in step 1.
Use one of these actions:
import-markdowncreatelistsearchquerygetadd-versiontranscriptstatusapply (an agent action, no client command of its own)diver-ready REVIEW_ID [--version N] [--by NAME], --off to unmark. The service records it and calls the factory webhook, which queues /deepdive for the Deep Diver owner (jgwill/Miadi#775). Until the service ships the /diver route, this returns 404.workflow REVIEW_ID --kind KIND [--version N] [--by NAME] [--dry-run], --off to withdraw. It signs review.workflow_requested straight to $MIADI_FACTORY_URL/api/factory/review-workflow (default :3335, secret MIADI_FACTORY_WEBHOOK_SECRET), and the factory queues a brief for the kind’s seat. GET on that route lists the kinds. A ui-screenwalk seat drafts the spec and the issue, then waits for Guillaume (jgwill/Miadi#818). A real request opens or reaches a session within 5 minutes: use --dry-run unless that is wanted.deletedownload-allThis is one skill because all actions share one service boundary and review lifecycle.
Every action takes an optional prompt after its targets:
/miadi-review <action> [targets] [prompt]
Targets are the URL, the Markdown file, or the review IDs (separated by commas or spaces). Everything after them is the person’s prompt. The service has no field for instructions, so the prompt is never sent to it. It steers what you do around the call: which result of a search to open, what to look for in a get, what to do once a create completes. For apply the prompt is the job itself. A prompt never lifts a rule in this skill: publishing and deleting still need the person’s approval of the exact act.
A live request requires MIADI_REVIEW_TOKEN. The client checks the process environment first, then reads that one literal key from ${MIADI_REVIEW_ENV_FILE:-$HOME/.env} without sourcing or executing the file. On a configured host, agents should call the client directly—never print, copy, or ask the human to paste the token.
To use a temporary process-local override:
export MIADI_REVIEW_TOKEN='...'
To select a different credential file deliberately:
export MIADI_REVIEW_ENV_FILE='/path/to/private.env'
The client defaults to:
https://miadi-review-service.vercel.app
Override it only when intentionally targeting another deployment:
export MIADI_REVIEW_BASE_URL='https://example.invalid'
Never print the token while diagnosing authentication. A 401 means the token is absent, stale, or does not match the target deployment.
This action is a direct upload. It sends url and markdown to POST /api/reviews/import; it must not fetch a transcript or invoke AI generation.
Run a dry check first:
python3 skills/miadi-review/scripts/miadi_review.py \
import-markdown @files/260827040423.md --dry-run
Then submit it:
python3 skills/miadi-review/scripts/miadi_review.py \
import-markdown @files/260827040423.md
The command accepts both ordinary paths and agent-style @path references. It extracts a YouTube URL from a Video URL: field unless --url is supplied explicitly:
python3 skills/miadi-review/scripts/miadi_review.py \
import-markdown notes/review.md \
--url 'https://www.youtube.com/watch?v=FExZvpVvYxA'
import-markdown uploads the selected Markdown through the dedicated manual-import endpoint. Before upload, it removes a leading Media-Review: or Media Review: wrapper from the first H1 so that wrapper text never becomes the article title. Other content is unchanged. For a new video, the app creates version 1; for an existing video, it appends a manual version instead of discarding the supplied content.
A 404 or 405 from /api/reviews/import means the APP has not deployed direct-import support yet. Report that deployment mismatch; do not fall back to sending Markdown as a transcript through the AI-generation endpoint.
Use create—not import-markdown—when the user wants the service to generate a review from a YouTube video or transcript.
The hosted service on Vercel stops every request after 60 seconds. Generating a review of a long video, such as an hour-long screenwalk, takes minutes, so create and add-version time out there. They leave either nothing or a version 0 record titled “Untitled review”. Don’t pay for a bigger plan, and don’t give up on the review. Run the same app on the host where its code lives:
packages/review-service/scripts/review-local.sh create 'https://youtu.be/<id>'
packages/review-service/scripts/review-local.sh add-version <review-id>
The script does three things:
packages/review-service/app on 127.0.0.1:3399 with the app’s own .env.local, which carries the same database, the same Gemini key and the same service token as the hosted one.A review made this way is written to the same database, so the hosted site serves it at its usual address. Any client command passes through, and MIADI_REVIEW_LOCAL_PORT, MIADI_REVIEW_LOCAL_TIMEOUT and MIADI_REVIEW_LOCAL_KEEP=1 adjust it. It needs app/.env.local (vercel env pull writes it) and app/node_modules. Verified 2026-10-02: the app starts and serves a read in about 18 seconds, and stops cleanly.
Before generating, query <video id> first. The video may already have a complete review from an earlier attempt that outlived its timeout. A version 0 record beside it is an orphan of a failed attempt. Name it, and delete it only on the person’s word.
Since 2026-10-05 the service keeps one transcript per review, beside its versions. get reports has_transcript, transcript_source (provided, or the Gemini model that wrote it) and transcript_url. The transcript command reads and stores it:
python3 skills/miadi-review/scripts/miadi_review.py transcript REVIEW_ID # read; has_transcript false when none
python3 skills/miadi-review/scripts/miadi_review.py transcript REVIEW_ID --out transcript.txt # read into a file, keep the JSON short
python3 skills/miadi-review/scripts/miadi_review.py --timeout 300 transcript REVIEW_ID --generate # Gemini transcribes the video
python3 skills/miadi-review/scripts/miadi_review.py transcript REVIEW_ID --file transcript.md # store a transcript as it is
409 unless --overwrite is given. Overwrite only on the person’s word.create --transcript-file now also stores that transcript with the new review and reports transcript_stored.add-version REVIEW_ID --stored-transcript generates the new version from the stored transcript, and --transcript-file from a file. Without either, the service watches the video again.--generate sends the whole video to Gemini. The route asks for 300 seconds, but the hosted service has stopped requests at 60 (previous section). When the hosted call times out, run scripts/review-local.sh transcript REVIEW_ID --generate, then transcript REVIEW_ID to read back what was stored.A review summarises, and the transcript the service keeps does not single out the person speaking. Only a transcript that does can show whether the person’s own words are in the recording at all. Run this right after a screenwalk is uploaded, before or beside its review:
node packages/review-service/skills/miadi-review/scripts/transcribe-video.mjs 'https://youtu.be/<id>' <vessel>/captures/<stem>/transcription-gemini.txt --speaker "William"
app/.env.local and app/node_modules, and returns in seconds.[script read: …].ffmpeg -af volumedetect on a short section).silences, spokenLines and token usage. If spokenLines is 0 or the silences cover the person’s turns, tell them the same day: the recording did not capture their voice.captures/<stem>/, next to its capture.json.usage is printed so the person can judge whether the cost is acceptable. Ask before running it on a batch.Gemini can still invent. On 2026-10-04 it, and the review, cited minutes past the end of a 20:58 video. Read the transcript against the video’s real length.
Earned 2026-10-04 (Episode 550, captures/screenwalk-261004-001): the person’s voice was missing from five days of screenwalks. William’s live test the same day found the cause. The screen recording captures his voice until he turns on speech recognition in the agent app, and from then on it captures noise. Whatever he dictated reached the agent as text, and it sits in the session logs with timestamps. YouTube’s captions and Gemini both heard only the voice reading the script, and the person’s ten minutes before scene 8 were silent. Nobody had listened back.
Create from a video:
python3 skills/miadi-review/scripts/miadi_review.py \
create 'https://youtu.be/BOOfy3Yshtw'
Create from a video while supplying transcript text:
python3 skills/miadi-review/scripts/miadi_review.py \
create 'https://youtu.be/BOOfy3Yshtw' --transcript-file transcript.md
List reviews:
python3 skills/miadi-review/scripts/miadi_review.py list --limit 20 --offset 0
Search on the server by keyword or partial/full review ID. It matches title, channel, video ID, and the latest review text. Each result carries score and matched_on (id or keyword):
python3 skills/miadi-review/scripts/miadi_review.py search 'structural tension' --limit 10
Query scans the review list on the client and matches metadata only (ID, title, channel, video ID, video URL). Use it when you have a full video URL:
python3 skills/miadi-review/scripts/miadi_review.py query 'WebRTC'
Retrieve a review, optionally selecting one version:
python3 skills/miadi-review/scripts/miadi_review.py get REVIEW_ID
python3 skills/miadi-review/scripts/miadi_review.py get REVIEW_ID --version 2
Generate a fresh version (add --stored-transcript or --transcript-file to generate from text instead of the video):
python3 skills/miadi-review/scripts/miadi_review.py add-version REVIEW_ID
Permanently delete one review and all stored versions. The exact ID confirmation is mandatory:
python3 skills/miadi-review/scripts/miadi_review.py \
delete REVIEW_ID --confirm REVIEW_ID
Download the latest version of every review as Markdown:
python3 skills/miadi-review/scripts/miadi_review.py download-all
By default this writes one .latest.md file per completed review directly into the skill’s cache/ subfolder:
cache/
├── manifest.json
└── Architecting_Agentic_Software_Engineering_with_Claude_Code.7e4c8ec5-b2ef-46c2-8695-1aa7e739d3c3.latest.md
Use --all-versions to also download every numbered version:
python3 skills/miadi-review/scripts/miadi_review.py \
download-all --all-versions
This keeps the .latest.md alias and adds files using the Safe_Title.UUID.vN.md format. The version-specific review title is preferred, converted to ASCII, and unsafe separators are replaced with underscores.
Use --clean-older-versions with the default latest-only mode to remove older .vN.md files for the fetched reviews. It retains a numbered file matching the current remote version, refreshes .latest.md, and does not touch unrelated cache files:
python3 skills/miadi-review/scripts/miadi_review.py \
download-all --clean-older-versions
--all-versions and --clean-older-versions are mutually exclusive.
Every cached Markdown file ends with its full public review URL:
---
## Online Review
[Title of the review](https://miadi-review-service.vercel.app/review/UUID)
Reviews still being generated are recorded in the manifest with no Markdown files and counted as pending. Re-running the command refreshes known .latest.md files from service Markdown, so the URL section is added exactly once. Older numbered files remain untouched unless --clean-older-versions is explicitly supplied.
A human or agent can choose another cache folder:
python3 skills/miadi-review/scripts/miadi_review.py \
download-all ./cache/miadi-reviews --page-size 50
The manifest contains review IDs, public URLs, source video URLs, latest-version numbers, and relative Markdown paths. It never contains the bearer token.
statuspython3 skills/miadi-review/scripts/miadi_review.py status ID1,ID2 ID3
For each review it reads the latest version and returns its title, URL, miadi-review:<uuid> reference, latest_version, has_transcript, the ## headings, and sections: whether the sections that steps 2 and 3 add are present (academic_fields, sources, related_review, internal_usage, definitions). next_step names the first step still owed. A review that cannot be read gets an error entry and the others are still reported.
A section flag only means a ## or ### heading starts with that name. Hand-written reviews use looser names, such as ## Academics or ### related reviews and miadi-chronicle episodes:, so read the headings before calling a step done or missing.
apply/miadi-review apply 6c3f477f-…,fcb78dc0-…,09de3362-…
In tmux 'asterion-miadi-circle-threads' I am drafting a prompt … Help me name that and ground it in a foundations/ packet …
The prompt names a job, and the reviews are its sources. The job can be naming a practice, grounding a term in a foundations/ packet, drafting a spec or answering a question. The person also gets the state of each review and the revisions the job suggests.
status on the IDs.get, or the public /review/<id>/raw). Read its stored transcript when the job needs the video’s exact words.foundations/ packet is deep-research-foundations, an episode is chronicle-episode, a GitHub issue is structural-issue-authoring. Cite each claim taken from a review as miadi-review:<uuid> vN, with the review’s timestamp when it gives one. When the prompt points at a tmux session or a file, read it. Type into another session only when the prompt asks for words to land there. Then put them at the end of the person’s draft with tmux send-keys -l, check first that the cursor sits there, never press Enter, and read the pane back. Leaving the words in your reply instead is a missed delivery: on 2026-10-06 the person’s verdict on the first apply run was “nothing sent”.A1, A2, …).Revisions to look for:
status and your reading.version 0 record or a public 404.Propose revisions and do not publish them. Each one goes out only after the person approves its exact text, through the publish discipline in miadi-review-academic-fields (dry run, one import, read-back).
When complete, CLI output also includes navigation fields:
{
"export_directory": "/full/path/to/cache",
"cd_command": "cd /full/path/to/cache",
"manifest_path": "/full/path/to/cache/manifest.json",
"exported_markdown_files": [
"/full/path/to/cache/Safe_Title.UUID.latest.md"
]
}
Use cd_command to navigate directly to the export folder. The absolute file list is printed for both humans and downstream agents; these machine-specific absolute paths are not persisted inside manifest.json.
Published reviews are public. To read one review, fetch it directly instead of running the authenticated client:
/review/<id>/raw Markdown as text/plain (?format=md for text/markdown)
/review/<id>/json review, selected version, and version list as JSON
/review/<id>/raw?v=2 any of the above, pinned to one version
/review/feed.xml RSS feed of reviews
Public /review/index, /review/list, and /review/feed.xml also enumerate reviews; do not assume the catalog is private because management/API listing requires authentication. Use the client for authenticated API listing, searching, querying, creating, importing, versioning, deleting, and download-all.
Read /review/<id>/json for the source video, selected version, model, and structured claims; fetch /raw?v=N when exact Markdown matters. A requested Mia–Ava dialogue is a new adaptation, not the review service’s output, a verbatim video transcript, or words spoken by the video’s participants. Preserve the review URL and selected version as provenance, distinguish the review’s timestamped claims from footage independently checked, and label any later dialogue or Chronicle script accordingly. The service generates and stores reviews; it does not generate, store, or authenticate dialogues.
Read the selected public /json and /raw version first. Stage a minimal local Markdown diff against that version (for example, a one- or two-sentence ## Intent naming a direction without claiming Miadi already has an evaluation system); preserve the rest of the review. import-markdown --dry-run checks the source URL and payload without publishing. Obtain approval of the exact amendment before importing once, then read back the new public version and its text. add-version regenerates with AI; it is not the tool for a surgical edit. If the review is still being shaped, defer episode creation even when an episode was requested; one or more review revisions may be needed before the version is ready to carry.
Read the latest version again just before the import. If another seat published a version after your diff, apply the approved edits on top of it, not over it, and apply every one of them. When the other version says the same thing in other words, the approved wording wins. A go covers the recommendations that came with the proposal, so do not turn them into new questions. Reopen an approved edit only when it has become impossible or unsafe, and say which. On 2026-10-08 a fork published v4 of 89f51d13 while another seat’s edits waited for approval. The seat applied five of seven as v5, kept the fork’s wording for the other two, and asked three new questions. The person had to ask what his go had meant, and the rest went out as v7. Grounding: miadi-foundation:delegation-and-adjustable-autonomy (sub-help, transfer of control).
## Intent section holds## Intent says how we intend to use this review and its video for the next step in the evolution of the Miadi Factory. Write a few lines, in the person’s voice or as “we”. Each line names a use and the next step it leads to. Where something is only wanted, state the current reality plainly next to it.
3cf740b9); “I am expecting to get from this review some discussion material that would make our systems implement and leverage Graph Engineering” (6394c566); “Would lead to implementing inside the repo jgwill/medicine-wheel an integration to ‘honcho’” (1ab1ffd7); “get insights on what’s important for me to learn” (12010459). Some carry a reservation (08a5612a).## Summary.Earned 2026-10-08 on 89f51d13. v4 put a closing’s title and description under ## Intent, and v7 kept the description. William’s comments on v8: “that is not an intent”, “this is passive description nothing related to what an ‘## Intent’ section would be about”, and “Reality is that we have NO MONEY, no crowd funding and nowhere where we present the miadi-factory to get funding… you are stating what we want with a false claim”. His definition, the same day: an Intent is “about how we intend to use this actual review and that screen walk for the next step in the evolution of the factory”. v12 is the first version written to it, and he accepted it: “we have achieved somewhere we can work with”. The accepted section and the rejected attempts are in examples/intent-acceptable-89f51d13-v12.md and examples/intent-rejected-89f51d13-v4-to-v9.md. Read both before writing an Intent.
A screenwalk sometimes shows work on something a viewer can install, often as a detour from what was planned. Examples are a plugin from jgwill/miadi-orchestration-kit (public) or a published package. A revision then gives the review one short section, ## Try It: <name>. It goes last, or just before ## Sources when the review has one, so a person reads the review before the install steps. It holds three things:
claude/mia-episode-companion in jgwill/miadi-orchestration-kit.claude plugin marketplace add jgwill/miadi-orchestration-kit
claude plugin install <plugin>@miadi-orchestration-kit
Check the plugin name against the kit’s .claude-plugin/marketplace.json before writing it.
Earned 2026-10-08 with the Episode 140 screenwalk (89f51d13). William could not work with Mia on the trading platform while her phone page cut his takes, so the session stopped and upgraded the mia-episode-companion plugin live. He named that unplanned upgrade as what a viewer can take from the video.
A review is also a reusable record in the Miadi chronicle, not only a page on this service. Since jgwill/Miadi#682 (2026-09-24) it has these names, and this skill’s client writes none of them:
| name | what it is |
|---|---|
miadi-review:<uuid> |
the portable reference an episode cites (references: or reviews: in episode.yaml) |
review:<uuid> |
the review’s one node on the chronicle wheel, type: knowledge, metadata.kind: miadi_review, with public_url and latest_version |
chronicle:<episode> → review:<uuid> |
one edge per episode; its relationship type says what that episode uses the review for |
talking_circle with subject_id: review:<uuid> |
a ceremony held about the review, in a circle of people |
Put an approved review version into an episode, or begin an episode from one. That write belongs to Miadi’s episode door, owned by the chronicle-episode skill: POST /api/chronicle/episodes/<ref>/reviews {review, relation?} or POST /api/chronicle/episodes {review}. After the review version is approved, published, and read back, hand its URL with ?v=N to the episode door as a separate act and report both results. The door records the review and relates it on the wheel; a talking circle opens only when a person is authorized to hold it. A writer token alone may leave the ceremony owed—do not report it as opened without a read-back. Never create the node or the edge by hand; Episodes 339 to 345 did, and the door now keeps those edges as they are.
Find where a review is used (read-only, no token; the wheel is $MIADI_CHRONICLE_MW_URL):
R=review:<uuid>
curl -s "$MIADI_CHRONICLE_MW_URL/api/edges?limit=all" | jq --arg r "$R" '[.[] | select(.to_id == $r) | {episode: .from_id, relation: .relationship_type}]'
curl -s "$MIADI_CHRONICLE_MW_URL/api/ceremonies?subject_id=$R&limit=all" | jq '[.ceremonies[] | {id, episode_path, circle_id}]'
Ask for ?limit=all: a bare edge list stops at 100 rows and silently leaves most episodes out. Inside Miadi, GET /api/chronicle/episodes/<ref>/reviews lists one episode’s reviews with their circles.
Versions. An episode records the version it used. add-version publishes a newer one and leaves that record alone; the episode room then shows “vN published” next to the version it used. Say so when you add a version to a review that episodes hold.
Once a review is published, two companion skills in this folder enrich it. Each group of changes becomes its own version:
../miadi-review-academic-fields/: corrects the generated text, adds ## Academic Fields after Summary (at most 55 words per field), and ends the review with ## Sources.../miadi-review-internal-usage/: adds ## Related Review (at most 55 words), ## Internal Usage tied to named teams and real packages, and ## Definitions.Run them in that order (jgwill/Miadi#692).
version >= 1 and public_url_verified: true before reporting success.id, url, and version only after those completion checks pass.reused when present; if true, say clearly that no new review was generated.0, no versions, or a public 404 is incomplete—not a successful review. A failed AI generation deletes its new row, so a version-0 record is either still generating or predates that rollback.--attempts 1..3 to control this. Direct Markdown import is submitted once to avoid duplicate manual versions.401, report that MIADI_REVIEW_TOKEN must be refreshed in the process environment or configured credential file; never ask the operator to paste it into chat.versions_deleted.miadi-review:<uuid>, so the review can be cited in an episode.--dry-run when verifying a path or extracted URL without network mutation.