Invenio user guide Plain-text guide for the Invenio Shopify app. Public pages live at /docs. # Getting started Getting started Invenio is an embedded Shopify app. Open it from Shopify admin, Apps, Invenio. You work inside your store. The live app host is https://invenio.srv1173388.hstgr.cloud. This guide matches what the app actually does in v2.3.0. First-time setup Home shows a setup checklist until all three items are done for this store: Store profile filled (business name and at least one town) Target keywords set (at least one keyword) NeuronWriter connected (an API key on the host plus a project id) The project id can come from NEURONWRITER_PROJECT_ID on the server, or you can save it on Products under NeuronWriter project. Fill Home settings On Home, scroll to Local SEO settings: Who, What, Where. These rank goals are the root input for article titles, article content, and catalog copy. Thin product titles borrow healthy assumptions from these fields. Target keywords. One search phrase per line. If the phrase already includes the town, Invenio keeps it as typed. Towns. One town per line. Used for local pages, blog topics, and NeuronWriter queries when the keyword does not already include the town. Business name, street, ZIP, phone, hours, pickup, store bio. Saved as facts the writer may state. Do not name other businesses. DataForSEO location. City and state for volumes and rank checks, for example Ringgold, GA. Save looks up DataForSEO names such as Ringgold,Georgia,United States, offers matches, and shows the resolved name and code. Audience mode. Local storefront or ships nationwide. Auto is fine for most stores. Posts per month. 1 to 4. Shopify publishes that many scheduled articles per calendar month. Planned topics in the Blogs queue do not count until they are built. Pause workers. Stops scheduled runs and Run now until you uncheck it. Daily email digest. On by default. Around 7:00 AM in the store timezone, Invenio POSTs a last-24-hours summary (JSON plus ready HTML) to the n8n digest webhook. Send test digest now posts the same payload without waiting. Click Save settings. Home keeps the first 3 unique keywords and the first 8 unique towns. Turn on the theme embed JSON-LD does not appear on the storefront until the Invenio local SEO app embed is enabled. Open Schema in Invenio, or open the theme editor, App embeds. Enable Invenio local SEO. Save the theme. Invenio does not edit theme files. Optional: add the Invenio Shop by Category app block on article or blog templates for category shortcuts. Optional: Search Console On Rankings, click Connect Search Console. Google opens in a new window (or the top window if a popup is blocked). After you approve read-only Search Console access, you return to Rankings. Invenio picks the property that matches this store's domain, or asks you to choose if none match. This spends no credits. What to do next On Products, save the NeuronWriter project id if it is not already set. Select a few products, click Generate, then open each product and approve the draft. On Blogs, create a NeuronWriter analysis only after you confirm (or reuse an existing query if the page says one already exists), then click Build scheduled posts. On Schema, save the types you want and confirm the embed is enabled. On Rankings, set a monthly rank budget if you want daily position checks. Home itself does not call NeuronWriter or OpenAI when it first loads. It does not spend credits. # Home Home Home is the store profile and control page. The left nav label is Home. There is no separate Settings tab. Store settings live here under Local SEO settings. Setup checklist If the store is missing a business name and town, keywords, or NeuronWriter, Home shows a checklist with Done or To do for each item. Links jump to the store profile, target keywords, or the NeuronWriter project field on Products. The checklist hides when all three items are complete. Suggested topics After the first paint, Home loads tags from this store's blogs that match the store category or a target keyword. Run now can use those tags as extra topics when a ready NeuronWriter query already exists. If no tags match yet, add overlapping tags on blog posts in Shopify. Run now Run now starts the background workers for this store: NeuronWriter research (reuse only), content, and meta. It does not create a paid NeuronWriter analysis. Run now is blocked when: Pause workers is checked You have not saved at least one keyword and one town A run is already in progress Watch the activity log for progress. This month's published post count loads after the first paint. NeuronWriter analyses on Home Scheduled jobs and Run now reuse ready queries. They never create a paid analysis unless you click Create missing NeuronWriter analyses and then Confirm create analyses. That confirm step can create one analysis per keyword and town pair that does not already have a ready query. It uses your monthly NeuronWriter plan (default 75 new analyses per month). Local SEO settings See Settings (/docs/settings) for every field. Save settings writes them for this store only. DataForSEO location, monthly cap, Test connection, month-to-date spend, the Daily email digest toggle, and Send test digest now live here too. Opening Home does not call DataForSEO. Search Console and Rankings Home shows whether Search Console is connected (from stored data only) and a Rankings card with tracked keywords and the last check. Connect and Check now live on Rankings. Competitors compares Google Business Profiles. Opening Home does not call Google, Serper, or DataForSEO. This month Shows blog posts built or scheduled this calendar month against the posts-per-month cap (1 to 4). Home, Blogs, and Reports use the same count. Planned topics from the Blogs content planner do not count until they are built. Also shows whether workers are paused or idle, the last run time, and the last run error if one exists. If ZIP and Where or Towns look like different US states (for example ZIP 81416 is CO while Ringgold, GA is 30736), Home shows a warning. Saved values are not changed. Generation uses the profile city and state as written. Activity log Shows the latest 5 worker events (publish, skip, error). Click View all to expand. Each row can include a link to the store page that changed. Home's first load only reads store settings. Activity and the post count load afterward. Opening Home does not spend Generate, Optimize, or NeuronWriter quota. # Products Products Products lists this store's catalog and writes SEO copy after you review it. Monthly quotas The page shows: Generate (OpenAI). Default 350 calls per store per month. Shared with Collections, bulk Image alt suggestions, and Local pages. Optimize (NeuronWriter). Default 10 runs per store per month. If OPENAI_API_KEY is missing, Generate writes stub copy you can still review. If NEURONWRITER_API_KEY is missing, Optimize writes a stub draft. NeuronWriter project Optimize uses one NeuronWriter project. Set NEURONWRITER_PROJECT_ID on the host, or save a project id on this page. The Home checklist treats a saved id plus an API key as connected. Filters Search by title or tag, pick a tag, group by none / category / tag, and filter by Shopify category. Changes stay inside the embedded app and keep the shop and host query params. On mobile the same filters apply in the page. Picking a tag such as Sangria hides products that do not have that tag. Generate and Optimize Select up to 10 products. An 11th checkbox is blocked. Click Generate or Optimize in the page header. Click Review copy in the SEO column, or open the product title, when a draft is ready to review. Compare current vs proposed meta title, meta description, and description. Click Approve and write to Shopify, or Discard draft. Discard leaves Shopify unchanged. Generate writes meta title, meta description, and description from OpenAI and this store's facts. Keywords come from Shopify category, product type, tags, and metafields, not only the Home target keywords. A store-wide keyword is used only when that product actually supports it. Optimize takes generated copy, or raw product data if you have not generated yet, and revises toward the top 1 competitor score in NeuronWriter. You must approve a diff before anything is written to Shopify. Products are backed up to JSON before a catalog write. Add image alt Each row has Add image alt. That sends the product photos to OpenAI vision with title, product type, category, collection, and store town, then writes alt text with Shopify fileUpdate. Each row uses its own fetcher and shows a success or error toast. It does not use the Generate quota. For a review-first batch of missing alt text, use the Image alt (/docs/image-alt) tab. Product editor Open a product to edit title, handle, description, SEO, and each image's alt text. Generate alt text on a card writes that one image immediately and says whether Save is still needed. Save uses the same write path. Generate and Optimize on the editor spend 1 of the matching monthly quota and create a draft for this product only. Check score If a ready NeuronWriter query matches this product, Check score runs evaluate-content on the current Shopify copy and shows the content score. That call does not create a query and does not spend Generate, Optimize, or analysis credits. If no ready query exists, the page says so and does not offer a score. # Collections Collections Collections works like Products for this store's collection pages. Quotas Generate and Optimize share the same monthly caps as Products: 350 Generate (OpenAI) and 10 Optimize (NeuronWriter) per store per month. Select up to 10 collections per run. The NeuronWriter project id on this page is the same store-wide project used on Products. Generate and Optimize Select collections. Click Generate or Optimize. Open a collection when the draft is ready. Approve the diff to write meta title, meta description, and description to Shopify, or discard it. Keywords are taken from the collection title and from the products in that collection (categories, types, tags). A Home target keyword is applied only when the collection actually supports it. Example: Red Wine can get Winery. Wine slushies or fruit wine are skipped unless that collection supports those terms. If none of the store keywords fit, Invenio uses collection-derived keywords and shows the source on the Keywords line. Image alt Each row has Add image alt for the collection image. Bulk missing-alt work for products is on Image alt (/docs/image-alt). Collection editor Open a collection to edit its copy, review a Generate or Optimize draft, and write image alt. Approve still happens before Shopify is updated. Bottom of page Generate bottom content (on demand) writes a 300 to 600 word description plus a 4 to 6 item FAQ into a preview. Save writes invenio.bottom_html and invenio.bottom_faq on the collection. Nothing auto-publishes. The Collection bottom app embed renders that block below products, with a Read more collapse and FAQPage schema only for visible Q&As. FAQ answers come from verified store facts only (address, hours, phone, pickup, collection products, policy pages). Prices, shipping times, guarantees, and health claims are not invented. Internal links are 3 to 6 real collections, pages, or articles. Generate for missing on the Collections list shows the missing count, Generate credit cost, and estimated dollar cost, then creates drafts only. Open each collection to review and Save. If a ready NeuronWriter query matches this collection, Check score runs evaluate-content on the current Shopify copy and shows the content score. That call does not create a query and does not spend Generate, Optimize, or analysis credits. # Blogs Blogs Blogs schedules real Shopify articles. Invenio creates them unpublished with a future publish date. Shopify publishes them when that date arrives. Store inputs The page shows the Home profile summary, how many posts you have used this month, and suggested topics from: Home keywords and towns Matching blog tags Collection titles The background content planner (collections, About page, homepage offer, store profile) Posts this month counts built or scheduled Shopify articles only. Planned topics do not use a slot until they are built. The cap is the posts-per-month value on Home (1 to 4 per calendar month). After one built post with a cap of 2, the page shows 1 of 2 remaining. Build without NeuronWriter writes posts with OpenAI from the store profile, towns, suggested topics, the content plan, and blog tags. It does not need a ready query and never creates a NeuronWriter analysis. Build with NeuronWriter still requires a ready query and only reuses it. The "topics ready" count matches the Suggested topics Ready query badges. NeuronWriter analyses NeuronWriter plans include 75 analyses per month by default (INVENIO_QUERY_CREATE_MONTHLY_CAP). The page shows how many Invenio created this month, and remaining analyses when the NeuronWriter API returns that number. Create 1 NeuronWriter analysis (uses 1 analysis) checks for an existing query first. If one already exists (ready or still running), the page shows a banner such as A NeuronWriter query for fruit wine already exists, reusing it and does not ask you to confirm. If none exists, Confirm: this uses 1 analysis is the only click that creates a paid query. A success or error banner always stays on the page (plus a toast). Invenio never creates a duplicate query. Scheduling never creates an analysis on its own. Build scheduled posts The page shows how many Generate credits the next OpenAI-only build will use (1 per article) and how many Generate credits remain (default 350). Build without NeuronWriter writes unpublished Shopify articles from the planned topic (title, intent, format, keywords, CTA) plus the store fact sheet. The writer opens with a 40 to 60 word answer, uses question-style H2s, follows the format template for that intent, links 2 to 5 catalog URLs, and ends with a short FAQ. Local hours and visit sections appear only in local audience mode. Code checks word count, SEO title (50 to 60 characters), meta (140 to 155), catalog links, fact-sheet prices, em dashes, and product adjectives that are not on the fact sheet. Up to 2 fix passes run with the measured numbers. Those retries do not spend extra Generate credits. If the post still fails, Invenio saves it as a Shopify draft and flags it in the queue. It requests a Pixabay featured image when PIXABAY_API_KEY is set (Unsplash or Pexels if that is the first configured key). SEO title and meta description write to Shopify article metafields global.title_tag and global.description_tag. The slug becomes the article handle and never includes invenio. The excerpt becomes the Shopify summary. HTML is sanitized (no markdown fences, no H1 in the body). It never creates a NeuronWriter query. Build with NeuronWriter runs only for topics that already have a ready query. Both stay within this month's posts-per-month cap (1 to 4, set on Home). A notice appears if no stock photo key is configured. Inline product and collection images in the article body use inline styles (max-width:320px) so Shopify themes cannot blow them up. The featured image is constrained (max-width:720px) with a Pixabay credit line directly under it: Photo credit: Name / Pixabay, linked to the Pixabay image page. Shop-the-collection items render as a simple card grid (image, then the link text under the image). Content planner A background planner keeps the Scheduled queue filled with upcoming topics. It always plans 8 store-unique topics, even when fewer posts are needed this month. Posts needed only decides which topics are scheduled first. The planner builds keyword clusters from search modifiers (how to, best, vs, gift, near the town), expands with niche terms from the catalog, and assigns one intent per topic: how-to, informational, comparison, buyer guide, seasonal, gift, or local. Each topic maps to a real product or collection CTA. Topics whose primary keyword is owned by a collection, product, page, home page, or earlier post are dropped. $0, hidden, unavailable, and discontinued products are not used as CTAs. Scoring is 100 points: keyword fit 30, commercial bridge 25, uniqueness 20, timing 15, local 10. When DataForSEO credentials are set, search volume and CPC for the store location add a bonus and can reorder topics. Volume is cached 30 days per keyword and location. Each month includes at least one traffic topic (how-to or informational) and one sales topic (buyer guide, comparison, or gift). Gift-heavy stores still get at least 2 non-gift topics. Audience mode is local storefront vs ships nationwide. Auto-detect uses hours, pickup, and shipping language on Home, and you can override it there. The plan is validated in code (8 topics, unique primary keywords, no do-not-target overlap, real CTAs). If it fails, Invenio re-asks once. Refresh plan uses at most two gpt-4o-mini calls. It never calls NeuronWriter. Find competitor gaps is on demand. It compares the top 3 local competitors from rank history with DataForSEO Labs ranked keywords and adds missing keywords as planned suggestions. Phrases that are numeric noise, out-of-area places, directories, national chains, or off-niche for the store's keywords and categories are dropped, and near-duplicates are merged. The page shows a loading state, then a result with the count, examples, or error, and writes an activity log row. If credentials are missing or the monthly cap is hit, the button does nothing harmful. Planned rows appear in the Scheduled queue with planned dates, intent, format, search volume, and CPC. If no store location is set, volumes use the United States. Build without NeuronWriter turns this month's remaining planned rows into unpublished Shopify articles. Next month stays planned until that month. Catalog links When a post is generated or rewritten, Invenio inserts 2 to 5 relevant products and 1 to 2 collections. Matching uses Shopify category, product type, tags, and title against the post topic and NeuronWriter terms. Store-wide keywords are not forced onto unrelated products. The same URL is never linked twice. Anchors are descriptive. The scheduled queue lists those links. On an unpublished article you can Remove link before Shopify publishes it. That edits the unpublished article only. Backlink suggestions Older published Invenio posts that could link to the new post appear as suggestions only. Published posts are not edited. Queue actions Each row shows title, status, publish date, keyword, town, score, and a link to Shopify admin. Planned rows also show search intent. You can change the publish date or remove a built article from Shopify. Refresh formatting re-renders an existing Invenio-built article with the current template (small images, Photo credit: Name / Pixabay under the image, links under images, no body H1). It does not call an LLM and does not spend credits. If the refresh would write an empty body or cut more than half the visible text, Invenio aborts and shows an error. Restore article writes the stored generated HTML back to Shopify (no AI) and applies the current template. Posts built before v1.6.9 do not have a stored body, so restore is not available and those articles must be rebuilt. Removing a post that has not published yet returns that slot to this month's post quota. Planned rows do not have Shopify admin actions until they are built. Built posts are created unpublished with a future publish date. # Image alt Image alt Image alt writes SEO alt text for catalog photos. There are two paths. Bulk image SEO (review first) The top of the page counts product images that are missing alt text and shows the Generate credit cost (1 credit per image). Nothing is written to Shopify until you review and apply. Click Generate suggestions. Invenio builds a batch of 5 suggestions at a time. Each suggestion includes alt text and a descriptive file name. This spends Generate credits. Review the proposed alt and file name. Apply selected writes the chosen drafts. Discard all suggestions drops them. If more images remain, generate again. Apply is the only step that updates Shopify for this path. Catalog images (write now) The table lists products and collections with their current featured-image alt. Add image alt sends that photo to OpenAI vision with: Original title Product type Category Collection Store town Then it writes alt text with Shopify fileUpdate (and product media update for products), reads it back, and shows Saved when the write verified. This path does not spend the Generate quota. You can also generate alt text on a product or collection editor, or from the Add image alt button on those list pages. If OPENAI_API_KEY is missing, Invenio writes stub alt text from the title so you can still see the flow. # Schema Schema Schema controls JSON-LD that the Invenio local SEO theme app embed injects on the storefront. Invenio never edits theme files. App embed The page shows whether the embed is enabled on the published theme, the theme name, and a link to the theme editor. Enable the app embed in the theme editor opens the published theme with activateAppId={client_id}/local-seo (local-seo is the app embed block handle). After you deploy the invenio-seo-schema extension, that link highlights Invenio local SEO under App embeds. Save the theme. If the live theme or storefront already outputs overlapping schema, Invenio warns about duplicates. Types you can toggle Organization. Business name, URL, E.164 telephone, and ISO country. Turn this off to suppress Invenio Organization when the theme already outputs one. Merge Organization sameAs keeps Invenio Organization and adds sameAs instead of skipping it. If the live theme already has Organization, Invenio warns about duplicates. LocalBusiness. Name plus town and address. Hours such as M-F 10am-9pm are stored as schema.org Mo-Fr 10:00-21:00 (or openingHoursSpecification). Telephone is E.164 (+1...). addressCountry is ISO US. Product. Name, image, description, sku, brand, offers (price, currency, availability), and url. Invenio writes Product schema only when the theme does not already output Product. Article / BlogPosting. Author and publisher Organization, datePublished, dateModified, image, about entities, mentioned products, and isPartOf Blog. Built from article metafields set by Invenio. No HowTo schema. BreadcrumbList. Product: Home > Collection > Product. Also page, blog, and article (Home > Blog > Post). FAQPage. Only when a post has a visible FAQ section. Empty FAQ markup is never emitted. Save schema settings writes the toggles to Invenio and to shop metafields. The embed reads those metafields on the storefront. Preview Sample JSON-LD for this store appears after you save a store profile and the catalog has a product or article. Use Google's Rich Results Test on a live product or article URL after the embed is enabled. Schema toggles do not spend credits. # Audit Audit Audit has a catalog SEO scan, Checkbot-style SEO checks, a Pages template scan, a slug checker, and an on-demand storefront speed pull. None of these spend Generate or NeuronWriter credits. Catalog issues Read-only scan of products, collections, and articles: Missing meta title Missing meta description Duplicate meta title or description across the scanned items Title over about 60 characters Description over about 160 characters Thin body copy (under about 50 words) Missing alt text when an image is present Open issues show as a count, then one card per item. Fix the item on Products, Collections, Blogs, or Image alt. This catalog scan does not write to Shopify. The monthly report's audit number is still this live open-issue count. SEO checks Grouped Errors and Warnings with counts. Each row links to the Invenio editor or Shopify admin: Missing or duplicate title tags and meta descriptions Title or meta length Missing H1 or multiple H1s on theme templates Broken internal links (paths that are not a current product, collection, page, or article) Redirect chains Missing image alt (Warning only) Missing canonical (when page HTML is present) noindex on a live page Pages Read-only list of Online Store pages and every templates/*.json or templates/*.liquid file on the main theme. Pages use title, handle, body or bodySummary, templateSuffix, and global title_tag / description_tag metafields for SEO (not Page.seo). Templates come from theme(id).files with filenames: templates/*, paginated, on the MAIN role theme (read_themes). Each template shows the sections it uses, whether those sections render an H1, and which pages use it. H1 counts only a heading setting rendered as h1 once per section or block instance (heading_tag or tag, or heading_size when Liquid uses it as the HTML tag), or one hardcoded