mindforgeai-creator-tools 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MindForgeAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# MindForgeAI creator tools and practical guides
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Prepare a clear video prompt and catch unsupported input settings before opening [MindForgeAI](https://mindforgeai.app/). This small offline helper is for creators and e-commerce teams exploring short motion drafts.
+
+**Release:** version 0.1.0. Check the [npm package page](https://www.npmjs.com/package/mindforgeai-creator-tools) for registry availability. The source and local-tarball procedures below work independently of registry publication. There is no public contact email in this project.
+
+## What this tool does
+
+- Compose a scene prompt from subject, motion, setting, camera and style.
+- Validate declared video parameters: text/image mode, prompt length, duration, orientation and reference-image metadata.
+- Explain invalid fields with machine-readable errors and a useful CLI exit code.
+
+It does **not** generate images or videos, call the website, authenticate users, upload files, check remaining quota, inspect actual image bytes or include model weights. It is not a MiniMax SDK or a replacement for the website's own validation. There are no dependencies, install hooks, telemetry or network requests.
+
+## Online tutorial center
+
+Read the [public MindForgeAI tutorial center](https://frequent-option-c81.notion.site/MindForgeAI-Tutorials-Free-Video-Drafts-and-H3-Image-Workflows-4170d247536b81bc9eabcb44a853c4ed) for browser walkthroughs, free limits and practical troubleshooting. These are first-party tutorials, not independent reviews or evidence of search-engine indexing.
+
+## Start with a practical guide
+
+| Your task | Guide |
+| --- | --- |
+| Understand the free entry points and prepare a first attempt | [Getting started](guides/getting-started.md) |
+| Write a focused scene prompt | [Free text-to-video](guides/text-to-video.md) |
+| Animate an authorized photo and check fidelity | [Photo-to-video](guides/photo-to-video.md) |
+| Make or edit a still image using the separate free H3 Image tool | [H3 Image workflow](guides/h3-image.md) |
+| Understand busy, failed and quota-limited attempts | [Troubleshooting](guides/troubleshooting.md) |
+
+These guides describe the documented MindForgeAI web presets checked on 2026-11-13, not every capability of the underlying models. Suggested prompts are not evidence of newly generated results.
+
+## Free access and limits
+
+The dedicated [free video tool](https://mindforgeai.app/free-ai-video) requires no sign-up, credit card or purchased credits. It offers about 5/10/15-second silent SD previews, 16:9 or 9:16 at 24 fps. MiniMax H3's preset is 896×512 landscape or 512×896 portrait; frame rounding can change exact duration. PinkCherry H3 v1.5 is a separate community fine-tune available in the form, not an official MiniMax release.
+
+Video access is limited to 3 submissions per network per UTC day and 50 sitewide, shared across the free video entry points and both profiles. Shared capacity can be busy. These are submission allowances, not a promise of successful clips or unlimited/free-forever service. Paid models and the signed-in credit workspace are separate.
+
+The separate [H3 Image generator](https://mindforgeai.app/minimax-h3-image) has its own image allowance. Do not assume that creating a free video gives access to paid images or that this helper checks live account entitlements.
+
+## Run from the independent repository
+
+Requires Node.js 20 or newer. The independent repository is available at [cydiz/mindforgeai-creator-tools](https://github.com/cydiz/mindforgeai-creator-tools).
+
+```sh
+git clone https://github.com/cydiz/mindforgeai-creator-tools.git
+cd mindforgeai-creator-tools
+```
+
+From that independent directory:
+
+```sh
+npm test
+node bin/cli.js prompt --subject "A ceramic cup" --motion "Steam rises slowly"
+node bin/cli.js validate --json '{"prompt":"A cup with rising steam","duration":5,"ratio":"16:9"}'
+npm pack
+```
+
+Expected prompt output:
+
+```text
+A ceramic cup. Steam rises slowly. Fixed camera.
+```
+
+Expected validation output:
+
+```json
+{"valid":true,"value":{"mode":"text","prompt":"A cup with rising steam","duration":5,"ratio":"16:9"}}
+```
+
+After creating the tarball, install that exact file in a temporary project:
+
+```sh
+npm install --ignore-scripts --no-audit --no-fund /absolute/path/to/mindforgeai-creator-tools-0.1.0.tgz
+```
+
+Then, in an `.mjs` file in the temporary project:
+
+```js
+import { buildVideoPrompt, validateVideoOptions } from 'mindforgeai-creator-tools';
+
+const prompt = buildVideoPrompt({
+  subject: 'A ceramic cup',
+  motion: 'Steam rises slowly',
+});
+console.log(prompt);
+console.log(validateVideoOptions({ prompt, duration: 5, ratio: '16:9' }));
+```
+
+The package does not send this prompt anywhere. To try it, copy the text into the website and explicitly submit there.
+
+## Validation and CLI behavior
+
+`validateVideoOptions(unknown)` returns either `{valid:true,value}` or `{valid:false,errors}`. Defaults are text mode, five seconds and 16:9. Unknown properties, unsupported durations and image metadata in text mode are errors. For image mode provide `{mime:'image/png',bytes:12345}`; metadata alone does not prove a file is valid.
+
+`buildVideoPrompt` throws a TypeError for missing/invalid scene fields and a RangeError if the combined prompt is too long. CLI `validate` prints JSON and returns exit code 2 for invalid input; invalid JSON and unsupported commands also return 2. `--help` returns 0. Only ESM imports are supported in this release.
+
+Use `node bin/cli.js profile` to inspect the dated offline constraints. If the web form has newer settings, follow the website rather than treating this snapshot as current service availability.
+
+## Relationship and rights
+
+MindForgeAI is the website discussed by these guides. MiniMax and other model names identify third-party technology; this project does not claim partnership, ownership of those models or universal commercial-output rights. Review the [product facts](https://mindforgeai.app/product-facts) and [terms](https://mindforgeai.app/terms-of-service) before using outputs.
+
+Only newly authored helper code, examples and tutorials are in this project. It contains no website implementation, commercial boilerplate, production configuration, user content, service workflow or weights. The original helper code, examples and tutorials in this repository are MIT licensed; see [LICENSE](LICENSE). This does not license the website implementation, templates, models or trademarks. Package availability can be checked on the npm package page linked above.

package/bin/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import {buildVideoPrompt, validateVideoOptions, videoProfile} from '../index.js';
+const help = `Offline MindForgeAI creator tools — no generation or network requests.
+Usage:
+  mindforgeai-tools prompt --subject "A ceramic cup" --motion "Steam rises slowly"
+  mindforgeai-tools validate --json '{"prompt":"A cup with rising steam"}'
+  mindforgeai-tools profile
+Invalid input exits with code 2; --help exits with code 0.`;
+function options(args) {
+  const result = Object.create(null);
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith('--')) throw new TypeError('Expected --name value.');
+    const equal = args[i].indexOf('=');
+    const key = args[i].slice(2, equal === -1 ? undefined : equal);
+    const value = equal === -1 ? args[++i] : args[i].slice(equal + 1);
+    if (!key || value === undefined || value.startsWith('--') || Object.hasOwn(result,key))
+      throw new TypeError('Missing value or duplicate option.');
+    result[key] = value;
+  }
+  return result;
+}
+try {
+  const [command,...args] = process.argv.slice(2);
+  if (command === '--help' || command === 'help' || command === undefined) console.log(help);
+  else if (command === 'profile') {
+    if (args.length) throw new TypeError('profile takes no arguments.');
+    console.log(JSON.stringify(videoProfile,null,2));
+  } else if (command === 'prompt') console.log(buildVideoPrompt(options(args)));
+  else if (command === 'validate') {
+    const flags = options(args);
+    if (Object.keys(flags).length !== 1 || !Object.hasOwn(flags,'json'))
+      throw new TypeError('validate requires only --json.');
+    const result = validateVideoOptions(JSON.parse(flags.json));
+    console.log(JSON.stringify(result,null,2));
+    if (!result.valid) process.exitCode = 2;
+  } else throw new TypeError('Unknown command. Use --help.');
+} catch (error) { console.error(JSON.stringify({error:error.message})); process.exitCode = 2; }

package/examples/cup.json

@@ -0,0 +1,6 @@
+{
+  "mode": "text",
+  "prompt": "A white ceramic cup on a wooden desk by a window. A thin ribbon of steam rises slowly. Fixed camera, soft morning light, one continuous shot.",
+  "duration": 5,
+  "ratio": "16:9"
+}

package/examples/quickstart.mjs

@@ -0,0 +1,4 @@
+import {buildVideoPrompt,validateVideoOptions} from 'mindforgeai-creator-tools';
+const prompt = buildVideoPrompt({subject:'A ceramic cup',motion:'Steam rises slowly'});
+console.log(prompt);
+console.log(JSON.stringify(validateVideoOptions({prompt}),null,2));

package/guides/getting-started.md

@@ -0,0 +1,27 @@
+# Start a free creative draft on MindForgeAI
+
+Use this guide when you want to explore one shot before paying for a production workflow. You need a browser and a visual idea; the dedicated free tools do not ask you to register or provide a credit card.
+
+## Choose the right starting point
+
+- [Free text-to-video](https://mindforgeai.app/free-text-to-video): describe a scene without uploading an image.
+- [Free photo-to-video](https://mindforgeai.app/free-image-to-video): upload one image and describe movement.
+- [Free H3 Image](https://mindforgeai.app/minimax-h3-image): generate or edit a still image, not a video.
+
+The first two video pages share the same free allowance, not three additional attempts on each page. As checked on 2026-11-13, video access allows three submissions per network per UTC day and fifty across the site, subject to shared capacity. Other paid image/video models use a separate account and credit workflow.
+
+## Make one deliberate attempt
+
+1. Open the relevant tool, read its current limits and start with one subject.
+2. For video, choose MiniMax H3 or the separate PinkCherry H3 community profile. Begin with about five seconds and choose landscape or portrait.
+3. Enter a prompt such as: “A ceramic cup on a desk by a window. A thin ribbon of steam rises slowly. Fixed camera, soft morning light.” This is a suggestion, not a newly verified output example.
+4. Click **Generate free video** once. Keep the task page open and follow its status instead of repeatedly submitting.
+5. When complete, play the whole result. Check the beginning, middle and end, then use **Open / download video** to save a result you want to keep.
+
+The free preset is a silent SD preview, not an automatically finished advertisement or an HD/2K deliverable. Add exact captions, music and edits separately if necessary. Generated faces, labels or product geometry can change.
+
+## Check your result, not just the completion label
+
+A completed task means a file was produced; it does not establish product fidelity, suitability for commercial use or a successful creative outcome. Review [recorded H3 examples and their limitations](https://mindforgeai.app/h3-video-examples). This guide does not claim a new generation or guaranteed turnaround time.
+
+If the tool is busy or an attempt fails, follow [troubleshooting](troubleshooting.md). Next, use [focused text prompts](text-to-video.md) or [prepare a photo](photo-to-video.md). Still-image needs belong in the [separate image workflow](h3-image.md).

package/guides/h3-image.md

@@ -0,0 +1,33 @@
+# Create or edit a still image with the separate H3 Image tool
+
+[MindForgeAI H3 Image](https://mindforgeai.app/minimax-h3-image) is a still-image generator and reference-guided editor. It is separate from the H3 video form, and the offline video helper in this repository does not validate all image-generator parameters.
+
+## Prepare your image task
+
+You can start with text, or one authorized PNG/JPG/WebP reference up to 5 MB. For text-to-image, specify subject, composition, materials and light. For an edit, describe both the change and what should remain recognizable.
+
+Suggested edit prompt:
+
+```text
+Keep the unbranded green bottle, silver cap and stone plinth. Change the ivory paper background to midnight blue paper with soft studio light. One bottle, no text or logos.
+```
+
+Use this only with your own suitable reference. It is a suggestion, not permission to upload someone else's image and not a guarantee of pixel-perfect preservation.
+
+## Generate a still image
+
+1. Open H3 Image and use **What would you like to create or change?** to enter your request.
+2. Optionally choose **Reference image (optional)** for reference-guided editing.
+3. Choose **Aspect ratio**. As checked on 2026-11-13, options are 1:1, 4:3, 3:4, 16:9 and 9:16.
+4. Review the displayed dimensions and image allowance, then click **Generate image** once.
+5. Wait for the result preview. Review the generated image and use its PNG download control to save it.
+
+The preset outputs approximately 2K-area PNG images: square 2048×2048; 4:3 2368×1760; 3:4 1760×2368; 16:9 2720×1536; 9:16 1536×2720. It does not expose all capabilities of the underlying model, such as 4K or many reference images.
+
+## Allowance and quality review
+
+The separate free image entry requires no sign-up or card and allows three image submissions per network per UTC day and fifty sitewide. Its image allowance is separate from the free video allowance, while processing capacity is shared. Neither allowance buys paid model credits.
+
+Inspect label text, subject geometry, reflections and unwanted changes. The [tool page](https://mindforgeai.app/minimax-h3-image) includes a recorded bottle image with prompt and seed; only those labeled records should be treated as actual examples. This guide does not claim that its suggested prompt was newly run.
+
+For a moving result, continue with [photo-to-video](photo-to-video.md) using an image you may process. For access or task issues, see [troubleshooting](troubleshooting.md).

package/guides/photo-to-video.md

@@ -0,0 +1,34 @@
+# Animate an authorized photo and review what changed
+
+Use [free image-to-video](https://mindforgeai.app/free-image-to-video) to explore motion from one still image. This creates new frames; it does not recover real footage from when the photo was taken.
+
+## Prepare the source
+
+Choose one PNG, JPG or WebP up to 5 MB. Keep the subject clear, leave space around its edges and use an image you have permission to upload. Avoid confidential product material or personal photos that you are not authorized to process.
+
+For an initial product draft, a stationary object with changing light is easier to review than a full rotation, splashing liquid and a scene change at once. A written movement description is required after uploading.
+
+Suggested prompt, not a verified new output:
+
+```text
+Keep the reference subject fully visible and stationary. Fixed camera; only a subtle change in background light. One continuous shot, no scene changes.
+```
+
+## Use the actual form
+
+1. Open the dedicated image-to-video page.
+2. Fill **Describe your video** with the motion request.
+3. Choose your file in **Upload image (required, PNG / JPG / WebP, up to 5 MB)**.
+4. Select the **Video model**, **Aspect ratio** and **About 5 seconds** initially.
+5. Review the shared allowance, then click **Generate free video** once.
+6. Wait for status and inspect the completed clip before choosing **Open / download video**.
+
+No registration or card is required for this free form. The three submissions per network per UTC day and fifty sitewide are shared with text-to-video and both free model profiles. Silent SD and approximate 5/10/15-second settings apply; shared GPU capacity can refuse a request.
+
+## Compare before publishing
+
+Compare the original photo against the beginning, middle and end of the video. Inspect faces, hands, bottle caps, silhouettes, packaging and text. A result that invents a label or changes a real product should be rejected or reworked; completion alone does not establish fidelity.
+
+There is no validated free H3 product-image fidelity example claimed in this guide. A [separate recorded Seedance photo-to-video case](https://mindforgeai.app/blog/turn-photo-into-video-with-ai) uses a different paid workflow; it is not evidence of the free H3 result or free model quality.
+
+If the source image itself needs a background change first, see the [still-image editing guide](h3-image.md). If you have no image, use [text-to-video](text-to-video.md). For busy and failed attempts, use [troubleshooting](troubleshooting.md).

package/guides/text-to-video.md

@@ -0,0 +1,32 @@
+# Turn a written scene into a free short video
+
+This workflow is for a single generated shot: a moving scene from a prompt, rather than assembling a full script with voiceover and captions. Use [MindForgeAI free text-to-video](https://mindforgeai.app/free-text-to-video).
+
+## Prepare a specific scene
+
+Write four elements: subject, setting, one action and camera. Restrained movement gives you fewer details to inspect than several simultaneous transformations. Avoid relying on generated lettering for exact product names or legal text.
+
+Suggested prompt:
+
+```text
+A white ceramic cup on a wooden desk beside a window. A thin ribbon of steam rises slowly. Fixed camera, soft morning light, the whole cup stays visible. One continuous shot.
+```
+
+This is an editable suggestion, not proof the model will preserve framing. The website's recorded cup case has a known cropping limitation; inspect the [actual case notes](https://mindforgeai.app/h3-video-examples) before expecting identical results.
+
+## Generate and review
+
+1. Open the free text-to-video page. Fill **Describe your video**; do not upload a reference if you want a text-led shot.
+2. Choose **Video model**: MiniMax H3, or the separate PinkCherry H3 v1.5 community fine-tune.
+3. Choose **Aspect ratio**. Use 9:16 for a portrait draft or 16:9 for landscape.
+4. Choose **Video duration**. Begin with **About 5 seconds**; about 10 and 15 seconds are also offered. Frame rounding may change exact duration.
+5. Read the allowance and click **Generate free video** once. Wait for the page's status; do not interpret a long wait as successful completion.
+6. Play the finished clip and use **Open / download video**. Check continuous motion, cropping, accidental text and the full subject silhouette.
+
+## What is free here?
+
+No sign-up, card or purchased credits are required for this dedicated entry. The allowance is three submissions per network per UTC day, fifty sitewide, shared with free photo-to-video and both video profiles. It is not an allowance for unlimited retries or a promise of three successful exports.
+
+MiniMax H3's web preset produces silent SD footage at 24 fps: 896×512 landscape or 512×896 portrait in existing recorded files. The free form does not expose HD/2K or audio-reference controls. The current workflow adds no MindForgeAI branding overlay, but generated logo-like marks are still possible. Inspect the output.
+
+The offline helper can compose a prompt and catch unsupported parameter values. It cannot generate a video or reserve free capacity. If you already have a source photo, switch to the [photo workflow](photo-to-video.md); for refusal, missing tasks or failed attempts, see [troubleshooting](troubleshooting.md).

package/guides/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshoot a free attempt without submitting repeatedly
+
+Use the dedicated [free video entry](https://mindforgeai.app/free-ai-video) or [H3 Image entry](https://mindforgeai.app/minimax-h3-image) and read its current status. This page explains the documented workflow; it is not a live service-health report.
+
+## The service is busy
+
+The shared device admits one task at a time. A new request can be refused while it is busy. Try later rather than rapidly pressing Generate. There is no guaranteed completion time and no promise of unlimited queue space. This helper package cannot bypass or reserve capacity.
+
+## The daily allowance is exhausted
+
+Each free video network allowance is shared across text/photo inputs and the available free video profiles. Visiting another tool page does not grant three more attempts. The separate image entry has its own image allowance, not general paid credits. Limits use the UTC date; the sitewide cap may also be reached. Follow the displayed message rather than creating additional accounts or attempting to evade restrictions.
+
+## A file or prompt is rejected
+
+For video, enter 5–2000 characters and choose about 5, 10 or 15 seconds and 16:9 or 9:16. For a reference, choose PNG, JPEG or WebP up to 5 MB. The dedicated photo page requires a file; a filename alone is not an upload. The offline helper validates declared metadata only. It cannot confirm whether the file contents are a valid image or will pass the server's checks.
+
+## The task is slow or missing
+
+Keep the task/status link private and follow the page's own status. A long wait is not proof that a file exists. A missing/lost task can indicate a backend interruption. Do not treat every network timeout as a safe opportunity to start a different request immediately; check the existing task first and follow any retry instructions.
+
+## The task completed, but the result is wrong
+
+Play the whole clip or inspect the full image. Reject results that misrepresent faces, labels or product geometry. Try one subject and smaller movement next time. Free H3 video is silent SD; absence of audio or HD is an expected limit of this preset, not necessarily a processing error. Generated text or logo-like elements are possible even without a branding-overlay step.
+
+## A different tool asks for credits or sign-in
+
+The main paid workspace and other models have separate conditions. Return to the dedicated free URL if you intended to use the limited free preview. Do not assume a free allowance pays for every model or grants commercial rights to any uploaded or generated content. Consult [product facts](https://mindforgeai.app/product-facts), [pricing](https://mindforgeai.app/pricing) and [terms](https://mindforgeai.app/terms-of-service).
+
+Continue with [a first attempt](getting-started.md), [text prompts](text-to-video.md), [photo preparation](photo-to-video.md) or [still-image editing](h3-image.md).

package/index.d.ts

@@ -0,0 +1,9 @@
+export interface Scene { subject: string; motion: string; setting?: string; camera?: string; style?: string }
+export interface VideoOptions {
+  mode: 'text' | 'image'; prompt: string; duration: 5 | 10 | 15; ratio: '16:9' | '9:16';
+  image?: { mime: 'image/png' | 'image/jpeg' | 'image/webp'; bytes: number };
+}
+export type ValidationResult = { valid: true; value: VideoOptions } | { valid: false; errors: Array<{field:string;message:string}> };
+export declare const videoProfile: Readonly<{ checkedOn: string; durations: readonly [5,10,15]; ratios: readonly ['16:9','9:16']; maxReferenceBytes: number; promptMinLength: number; promptMaxLength: number }>;
+export declare function buildVideoPrompt(input: Scene): string;
+export declare function validateVideoOptions(input: unknown): ValidationResult;

package/index.js

@@ -0,0 +1,60 @@
+const allowed = (object, keys) => Object.keys(object).filter(key => !keys.includes(key));
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const imageTypes = ['image/png', 'image/jpeg', 'image/webp'];
+
+/** Offline documentation snapshot; not a live entitlement or availability check. */
+export const videoProfile = Object.freeze({
+  checkedOn: '2026-11-13',
+  durations: Object.freeze([5, 10, 15]),
+  ratios: Object.freeze(['16:9', '9:16']),
+  maxReferenceBytes: 5 * 1024 * 1024,
+  promptMinLength: 5,
+  promptMaxLength: 2000,
+});
+
+export function buildVideoPrompt(input) {
+  if (!record(input)) throw new TypeError('Provide a scene object.');
+  const keys = ['subject', 'setting', 'motion', 'camera', 'style'];
+  if (allowed(input, keys).length) throw new TypeError('Unknown scene field.');
+  for (const key of keys) {
+    if (input[key] !== undefined && (typeof input[key] !== 'string' || !input[key].trim()))
+      throw new TypeError(`${key} must be non-empty text.`);
+  }
+  if (!input.subject?.trim() || !input.motion?.trim())
+    throw new TypeError('subject and motion are required.');
+  const prompt = [input.subject, input.setting, input.motion, input.camera ?? 'Fixed camera', input.style]
+    .filter(value => value !== undefined).map(value => value.trim().replace(/[.!。]+$/u, '')).join('. ') + '.';
+  if (prompt.length < 5 || prompt.length > 2000)
+    throw new RangeError('The combined prompt must be 5–2000 characters.');
+  return prompt;
+}
+
+/** Checks declared parameters only; never reads, uploads or verifies image bytes. */
+export function validateVideoOptions(input) {
+  const errors = [];
+  const add = (field, message) => errors.push({field, message});
+  if (!record(input)) return {valid:false, errors:[{field:'input', message:'Expected an object.'}]};
+  for (const key of allowed(input, ['mode', 'prompt', 'duration', 'ratio', 'image']))
+    add(key, 'Unknown field.');
+  const mode = input.mode === undefined ? 'text' : input.mode;
+  const duration = input.duration === undefined ? 5 : input.duration;
+  const ratio = input.ratio === undefined ? '16:9' : input.ratio;
+  if (!['text', 'image'].includes(mode)) add('mode', 'Choose text or image.');
+  if (!videoProfile.durations.includes(duration)) add('duration', 'Choose the number 5, 10 or 15.');
+  if (!videoProfile.ratios.includes(ratio)) add('ratio', 'Choose 16:9 or 9:16.');
+  if (typeof input.prompt !== 'string' || input.prompt.trim().length < 5 || input.prompt.length > 2000)
+    add('prompt', 'Enter 5–2000 characters of scene or movement text.');
+  if (mode === 'text' && input.image !== undefined) add('image', 'Text mode must not include image metadata.');
+  if (mode === 'image') {
+    if (!record(input.image)) add('image', 'Provide declared mime and bytes for one reference image.');
+    else {
+      for (const key of allowed(input.image, ['mime', 'bytes'])) add(`image.${key}`, 'Unknown image field.');
+      if (!imageTypes.includes(input.image.mime)) add('image.mime', 'Choose image/png, image/jpeg or image/webp.');
+      if (!Number.isSafeInteger(input.image.bytes) || input.image.bytes < 1 || input.image.bytes > videoProfile.maxReferenceBytes)
+        add('image.bytes', 'Expected an integer from 1 to 5242880 bytes.');
+    }
+  }
+  if (errors.length) return {valid:false, errors};
+  return {valid:true, value:{mode, prompt:input.prompt.trim(), duration, ratio,
+    ...(mode === 'image' ? {image:{mime:input.image.mime, bytes:input.image.bytes}} : {})}};
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "mindforgeai-creator-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Offline scene-prompt builder and input checks for documented MindForgeAI free video settings.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://mindforgeai.app/",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "bin": {
+    "mindforgeai-tools": "./bin/cli.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bin/cli.js",
+    "guides/*.md",
+    "examples/*.json",
+    "examples/*.mjs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "video",
+    "prompt",
+    "validation",
+    "offline",
+    "mindforgeai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cydiz/mindforgeai-creator-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cydiz/mindforgeai-creator-tools/issues"
+  }
+}