=== ACS Article Generator ===
Contributors: hanchan
Tags: ai, content, gemini, seo, drafts
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Builds category hub pages from the posts you already have, and drafts new articles in your site's own voice, with your own Google Gemini key.

== Description ==

ACS Article Generator does two things with a Google Gemini API key that belongs to you: it turns a category you have already filled with posts into a hub page, and it drafts new articles in the voice the rest of your site already uses. Everything it makes is saved as a draft.

= Category hub pages, with links that cannot be wrong =

Pick a category. The plugin reads every published post in it and drafts a single page that introduces the subject, says in two or three sentences what each post actually covers, suggests where a newcomer should start and what to read next, and finishes with an FAQ.

The part that matters is how the links are made. **The model is never allowed to write a link.** It refers to your posts by numbered placeholders, and before anything else happens the plugin deletes every anchor tag, every address and every domain name from the reply. Only then does it replace each placeholder with an anchor built from a permalink read out of your own database a moment earlier. A hub page therefore cannot contain a broken link, a link to somebody else's site, or a plausible-looking URL that was never real. If the model skips a post, the plugin adds it in a closing list, so the hub is always a complete index of the category.

A category with no published posts is never built. Building again creates a new draft and leaves the previous hub page untouched, and the plugin records which posts each hub covered, so you can see at a glance what has been published since the last one.

= Articles in your site's voice =

Before it writes anything, the plugin can read the posts you have already published and write down how this particular site sounds: the sentence endings, the heading style, the shape of an article, the phrases that keep coming back. That style guide is yours to edit, and it is handed to the model on every run, so a draft reads like the rest of the site instead of like a generic AI article.

One run produces a complete first draft: an SEO title, a meta description, a slug, categories and tags, and a body of at least 3,000 characters built from h2 and h3 sections with internal links to your own posts.

**What you get**

* Category hub pages built from your real posts, with every internal link constructed by the plugin rather than written by the model
* A record of which posts each hub page covered, so the next build shows you what has changed
* A style guide learned from your own published posts, which you can edit by hand
* Eight subject suggestions that avoid titles you have already used
* A full article in one pass: SEO title, meta description, slug, tags, categories and body
* Your choice of length, from about 3,000 characters up to about 8,000
* A field for your own first hand experience, woven into the article rather than summarised
* A product or offer name to introduce where it genuinely fits
* External links with your choice of anchor text, rel value (nofollow, sponsored or ugc) and position, added for you if the model leaves one out
* The SEO title and meta description filled in for ACS SEO Plus or Yoast SEO, and always written to the post excerpt

**Always a draft**

Everything this plugin creates is saved with the status `draft`. There is no publish button, no scheduler and no automation anywhere in it, and it never overwrites a page you already have. A person reads the article before the public does. That is a design decision, not a limitation.

**Nothing is locked**

This plugin is complete on its own. Nothing in it is metered, time limited, counted or reserved for a paid tier. It never asks for a licence key, never asks you to create an account, and contacts no server belonging to the author. You bring your own Google Gemini key and Google bills you for what you use.

Image generation prompts, image insertion with WebP conversion and AI alt text, batch drafting and in-editor AI rewriting are sold separately as an add-on at ACS Developer (https://acs-developer.com/acs-article-generator/) and are not part of this plugin.

**Requirements**

* A Google Gemini API key of your own, from https://aistudio.google.com/apikey
* An account that can edit posts, to use the plugin, and an administrator account to change its settings

== External services ==

This plugin relies on one third-party service: the **Google Gemini API**, operated by Google. It is required, because the plugin does the writing by calling that API with a key that you supply.

**When a request is made**

Only when a logged-in editor presses one of the three buttons in the plugin. Nothing is sent on a page view, on a schedule, or in the background. Visitors to your site never cause a request.

**Where the request goes**

`https://generativelanguage.googleapis.com/v1beta/models/<model>:generateContent`

**What is sent**

* Your Google Gemini API key, in the `x-goog-api-key` request header
* When you press *Analyse my published posts*: the titles of the published posts being analysed and an extract of up to 1,500 characters from each of them, plus the language setting
* When you press *Build the hub page*: the name of the category, and the title, publication date and an extract of up to 600 characters for each published post in it (up to 40 posts), plus the site description and the saved style guide. Permalinks are **not** sent, because the links are built locally afterwards
* When you press *Suggest subjects*: the titles of up to 100 published posts, the site description you saved, and the saved style guide
* When you press *Write the draft*: everything you typed into the form (the subject, extra instructions, your own experience, the product name and the external links), the site description, the saved style guide, and the titles and permalinks of up to 60 published posts

No post content other than the extracts described above is sent, and no information about your site's visitors is ever sent.

**What is not sent, and where nothing goes**

The plugin contacts no other host. It sends nothing to the plugin author, has no telemetry, no update check of its own, no analytics, no external fonts and no external scripts.

Google's terms and privacy policy govern your use of that API:

* Gemini API Additional Terms of Service: https://ai.google.dev/gemini-api/terms
* Google Privacy Policy: https://policies.google.com/privacy

== Frequently Asked Questions ==

= Do I need an account with you? =

No. There is no account, no licence key and no sign-up. You need a Google Gemini API key, which you create yourself at https://aistudio.google.com/apikey.

= What does it cost? =

The plugin is free. Google bills you directly for the API calls you make with your own key. A single long article is one request.

= Can it publish automatically? =

No, and it is not meant to. Every article and every hub page is saved as a draft. There is no publish action, no scheduling and no cron job in the plugin at all.

= Can a hub page link to a post that does not exist? =

No. The model is not allowed to write links. Every anchor tag, address and domain name is stripped out of its reply, and then the plugin inserts links it built itself from permalinks read out of your database. Nothing in a hub page's internal links comes from the model except the position it chose to put them in.

= What happens when I build a hub page for the same category twice? =

You get a second draft. The first one is left exactly as it is, published or not. The plugin stores the list of posts each hub covered, so the second build tells you how many articles are new since the first and how many have left the category.

= Can it overwrite a page I already have? =

No. It only ever creates new drafts.

= How is my API key stored? =

In this site's options table, in its own row that is not loaded on every request. Once saved it is never displayed again: the settings field is always empty, and the key is never written into an error message, a log or a URL. It is read only when a request is made and travels in a request header. WordPress options are not encrypted, so treat database access to your site as access to the key, and delete the key with the checkbox on the settings screen if you stop using the plugin. Uninstalling the plugin deletes it.

= Does it really learn how my site writes? =

It reads the most recent published posts, up to thirty of them, and writes a style guide describing what it found. You can read that guide, disagree with it and edit it. What you leave in the box is what the model is told to follow.

= The article came out shorter or thinner than I asked for. =

Length is an instruction to the model, not a guarantee. If the reply is cut off because the model ran out of output room, the plugin automatically tries once more at the next length down and tells you if that fails too.

= Which SEO plugins does it fill in? =

ACS SEO Plus and Yoast SEO, if either is active. The meta description is always saved to the post excerpt as well, which is what WordPress itself uses when no SEO plugin is installed.

= Is the article ready to publish? =

No. It is a first draft. Check every fact, figure, name and link before you publish it, the same way you would with any draft written by someone else.

= Which languages does it write in? =

It follows your site's language by default, and you can choose another from a list on the settings screen. The plugin's own interface is in English.

== Screenshots ==

1. Category hub page: pick a category, add optional instructions and build. The result says how many posts the hub covers and how many are linked from the body.
2. A hub page draft built from six posts. Every link was built by the plugin from real permalinks; the post the model did not mention is added under "Also in this category".
3. Subject suggestions: eight articles the site has not written yet, each with a search phrase and an existing post to link to.
4. Writing a draft with your own experience, a product name and an external link with its anchor, rel value and position. The result is saved as a draft.
5. House style: the style guide learned from your own published posts, which you can edit before it is used.
6. Settings: your own Gemini API key (never shown again once saved), model, site description, language and draft handling.

== Changelog ==

= 1.0.2 =
* Japanese translation: spacing between English words and Japanese text now follows the WordPress core Japanese style.

= 1.0.1 =
* Japanese translation added.
* Settings: a saved API key is now shown as a clear "saved" badge with a masked field.

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.0.2 =
Japanese translation polish only. No functional change.

= 1.0.1 =
Adds a Japanese translation. No change to how articles are generated.

= 1.0.0 =
First release.
