NONINT SOFTWARE RECIPES — AGENT PUBLISHING GUIDE Version 1, 2026-11-10 Purpose ------- A recipe shares how to recreate an application, not necessarily its complete source tree. Package the useful ideas, requirements, edge cases, acceptance tests, designs, and small snippets for genuinely complicated parts. Include reference screenshots or other artifacts when they help establish the target. The GitHub repository is the distributable recipe. Nonint is its catalog. Information to collect from the author -------------------------------------- Ask only for information missing from the current conversation or explicitly approved defaults. Collect it in one short message where possible: 1. Which application/project and scope are we packaging? What must stay out? 2. The author's description, in their own words. Preserve it verbatim apart from line-ending normalization. Do not invent, summarize, or silently edit it. The blog uses plain text; blank lines become paragraphs. 3. Suggest 3–5 short, distinctive names with a recommended choice; let the author choose or explicitly delegate the final choice. Derive a stable slug. 4. GitHub owner/organization, repository name, and public visibility approval. 5. License choice and any third-party attribution constraints. Never silently choose a license for someone else's work. If undecided, prepare privately. 6. Publish this recipe to GitHub and Nonint now, or leave it as a private draft? The agent owns the supporting artifacts: do not make the author write the requirements/tests, choose every screenshot, or organize the repository. Ask focused follow-ups only for ambiguities that would change the product. An explicit request to publish this identified recipe can supply approval; "package this" alone should not silently expose private work. Repository contents ------------------- Use a fresh staging directory and a fresh Git history, separate from the application's repository. Do not copy its .git directory or push all branches. Include only material that helps a new agent recreate the product. One useful shape (omit or combine files that do not earn their place): README.md selected name, exact author description, quick start BUILD.md build-agent entrypoint and recreation instructions recipe.json catalog metadata (format below) REQUIREMENTS.md behavior, boundaries, non-goals, data, constraints ACCEPTANCE.md observable checks, examples, edge cases, failure modes designs/ diagrams or decisions for complicated parts snippets/ small reusable code fragments, with provenance reference/ screenshots, fixtures, recordings, example outputs LICENSE the author's chosen license, when approved BUILD.md should tell the consuming agent to read the requirements, propose a brief implementation approach, build with appropriate current tools, and verify against acceptance criteria and reference artifacts. Separate required behavior from incidental implementation details. State any unresolved choices and prerequisites. Do not promise bit-for-bit reproduction across models. Favor executable or objectively checkable acceptance tests over visual claims alone. Record responsive behavior, empty/loading/error states, accessibility, data persistence, and security boundaries when relevant. Reference screenshots should come from the real product; label mockups as mockups. Do not claim a fresh reconstruction was tested unless it actually was. Before committing, inspect the complete staged file list and contents for credentials, .env files, private keys, personal data, private host details, production databases, logs, unlicensed assets, and unintended source code. Use explicit git add paths. A secret scan is useful, not a substitute for review. Never include agent authentication in recipe.json or other public files. recipe.json (version 1) ----------------------- { "schemaVersion": 1, "slug": "chosen-name", "title": "Chosen Name", "description": "The author's exact description.\n\nA second paragraph.", "githubUrl": "https://github.com/OWNER/REPOSITORY", "ingredients": ["ideas", "requirements", "tests", "snippets", "designs"], "screenshots": [ {"path": "reference/overview.png", "alt": "A useful description of the reference screenshot"} ] } List only ingredients actually provided; any subset, including an empty list, is allowed. The description and a valid GitHub repository URL are required to publish, but a draft can omit them. The slug becomes a stable Nonint URL and cannot be changed in the editor. Use lowercase hyphenated words, max 100 chars; "preview" is reserved. Titles max 200 chars; descriptions max 30,000 chars. Screenshots are optional. The packaging helper accepts up to 8 PNG/JPEG/WebP/ GIF files, max 8 MiB each and 24 MiB total, with nonempty alt text. Paths are relative to recipe.json and must remain inside that directory, including after resolving symlinks. Other artifacts can live in the GitHub repo without being embedded in the catalog. Prefer smaller screenshots for fast page loading. Publishing workflow ------------------- 1. Finish the package, preserve the author's description, and get any missing title/license/publication choices. Do not invent descriptions to unblock it. 2. Use an authorized GitHub connector or authenticated GitHub CLI. With gh, check the signed-in account before creating a repository. Do not print tokens. A typical approved creation from a fresh local repository is: gh repo create OWNER/REPOSITORY --public --source STAGING --remote origin --push Quote arguments correctly for the current shell. If the repository already exists, inspect its owner, visibility, and remote; do not force-push, delete, or change its visibility. For an update, make an ordinary reviewed commit. 3. Verify the repository and expected commit are reachable anonymously before publishing its Nonint entry. Check the actual GitHub page or API; a valid URL alone does not establish that it exists, is public, or has the right content. 4. With a checkout of the Nonint platform, prepare a bounded image bundle: node scripts/prepare-recipe.mjs PATH/recipe.json TEMP/recipe-bundle.json Use a new output path. This validates metadata, reads only explicitly listed image files, and creates content-addressed local image URLs. It does not execute the recipe or contact GitHub. Keep the bundle outside the public repo. 5. Using an already authorized Nonint SSH connection, pipe the bundle's bytes to the server-side helper. The following POSIX example uses an SSH alias; obtain the appropriate host/identity from the owner or local configuration: ssh NONINT_HOST nonint-recipe import - --draft < TEMP/recipe-bundle.json PowerShell equivalent (for ordinary UTF-8 JSON bundles): Get-Content -Raw -Encoding utf8 TEMP/recipe-bundle.json | ssh NONINT_HOST nonint-recipe import - --draft The helper prints the private preview URL and saved state. It does not need a browser session, the authoring password, or a public API token. It runs as Nonint's service user and changes only recipe/media records. Root SSH itself is broad access: do not distribute it to untrusted agents. Provision a separately approved constrained SSH command/key for those agents if needed; this workflow does not grant one automatically. 6. When publication is authorized, use the same command with --publish. If an existing slug has different content, import refuses unless --replace is explicitly supplied. Review the current recipe before replacing it. Identical retries do not duplicate entries; --draft never updates the public snapshot. 7. Verify https://nonint.com/recipes and /recipes/SLUG anonymously: exact author description, images, GitHub link, and git clone command. Confirm Main and High volume are unchanged. Return the repository URL, catalog URL, commit, what was validated, and any remaining limitation. If a step fails --------------- Stop at the boundary that failed. GitHub and Nonint are not one transaction: the repository may already be public even if catalog publishing fails. Report that accurately and retry the import after fixing the problem; do not delete the repository. A failed publish can leave a safely saved private recipe. Do not loop on authentication failures, create fresh credentials, weaken auth, or overwrite another recipe to work around an error. Manual editing and privacy -------------------------- The owner can manage recipes at https://nonint.com/admin/recipes using the same password login as the blog. Save draft does not alter a live recipe. Private preview requires login. Publish updates the public snapshot. Unpublish removes the catalog entry but retains the draft and does not delete the GitHub repo. Previously published image URLs remain public/cached; unpublishing is not a secret-revocation tool. A public GitHub repo is public regardless of blog state. No GitHub API calls occur on visitor page loads. Metadata and catalog images live on the Nonint server. Full recipe repositories live on GitHub by design. For browser-authorized integrations, /api/admin/recipes supports GET/POST and /api/admin/recipes/SLUG supports GET/PUT. POST /publish takes expectedUpdatedAt; POST /unpublish removes only the public snapshot. PUT also requires the latest expectedUpdatedAt. All require the existing owner session, authoring CSRF token, and same-origin mutation checks. Do not borrow a human browser session for an unattended agent; use the SSH helper instead. References ---------- https://cli.github.com/manual/gh_repo_create https://cli.github.com/manual/gh_auth_login Realistic automation -------------------- Once an agent has this guide, the project, GitHub access, and authorized Nonint SSH access, packaging and publishing can be mostly hands-off. Your description and decisions about name, owner, license, and public release are the human inputs. Explicitly recorded defaults can remove repeated questions. An agent without those credentials can still produce a complete local package and bundle; it cannot honestly promise to publish them. This workflow prepares a recreation specification, not a guarantee that every future model will build an identical or correct application without iteration.