=== TopNotch AI SEO Tool ===
Contributors: topnotchllc
Tags: seo, content audit, keywords, internal linking, search console
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.4.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Audit keyword ownership, intent overlap, pillar pages, long-tail opportunities and internal links, with optional Google Search Console data.

== Description ==

TopNotch AI SEO Tool is a site-agnostic SEO and content-planning plugin. It builds a local map of the WordPress site where it is installed, compares imported keyword research against existing and planned content, and can optionally enrich decisions with real Google Search Console query/page performance data.

It is designed to answer:

* Does this keyword already have an owner on my site?
* Should I ignore it as a new URL and merge it into an existing page?
* Is it partly covered and better reframed?
* Is it a unique long-tail topic?
* Does the site already have a suitable pillar page?
* Should a new cluster start with a new pillar?
* Which existing pages should link to the new article?
* Which unique topics have the strongest opportunity?
* Are multiple pages appearing for the same Search Console query and worth reviewing for cannibalization?

= Keyword decisions =

After Site Audit, import CSV, XLSX or JSON keyword research. Each keyword receives an editorial recommendation:

* Already Exists
* Ignore New URL / Merge
* Merge or Reframe
* Write Long-Tail
* Write New Pillar
* Write Standalone
* Needs Review

= Site audit =

The audit can index public WordPress content types that have an admin UI, including posts, pages, and compatible custom post types such as products. It can include published, scheduled, draft, pending, and private content so planned URLs are not mistaken for gaps.

Signals include titles, slugs, headings, public taxonomy terms, content terms, common SEO focus-keyword meta, word depth, internal links, entities, and search-intent compatibility.

Common focus-keyword fields supported include Rank Math, Yoast SEO, AIOSEO, and SEOPress. Developers can extend these using `nci_focus_keyword_meta_keys`. Post types can be customized with `nci_scan_post_types`.

= Pillars and clusters =

Existing pillar candidates receive an internal structural score based on content depth, headings, inbound/outbound internal links, and publication status. This is not a Google authority score.

Unique imported keywords are grouped into topical clusters. If an existing pillar fits, the plugin recommends the new article as a long-tail child and suggests linking to that pillar. If no suitable pillar exists and several unique keywords form a cluster, the strongest candidate can become Write New Pillar.

= Opportunity scoring =

Opportunity Score can use:

* uniqueness / current coverage
* cannibalization risk
* internal topical support
* imported search volume
* imported keyword difficulty
* Google Search Console impressions, clicks and average position when connected
* freshness/trend fields when supplied

The plugin does not fabricate live keyword volume or live Google keyword difficulty. When external metrics are absent, confidence is labeled Internal-only.

= Google Search Console integration =

Version 0.4 adds an optional direct connection to Google Search Console.

The administrator supplies their own Google OAuth 2.0 Web application Client ID and Client Secret. The plugin requests the read-only Search Console scope, lists properties available to that Google account, and can sync Search Analytics rows grouped by query and page.

Synced data is stored in the local WordPress database and feeds into the opportunity engine. The Search Console tab also flags queries that appear for more than one page as cannibalization review signals. Multiple ranking pages do not automatically mean a problem; branded, navigational or broad queries can legitimately map to several URLs.

The default sync requests up to 5,000 query/page rows for the selected date range. Developers can change this up to the Search Console API request maximum with the `nci_gsc_row_limit` filter. Search Console itself may return top rows rather than every row, so the local report should not be treated as an exhaustive export.

== External services ==

Google Search Console integration is optional and only runs after an administrator explicitly configures and connects it.

When connected, the plugin communicates directly with these Google services:

* Google OAuth authorization: `https://accounts.google.com/o/oauth2/v2/auth`
* Google OAuth token service: `https://oauth2.googleapis.com/token`
* Google Search Console API: `https://www.googleapis.com/webmasters/v3`

Data sent to Google includes OAuth credentials/authorization data and the selected Search Console property/request parameters. Google returns access/refresh tokens, accessible Search Console properties, and requested Search Analytics performance data. The plugin requests `https://www.googleapis.com/auth/webmasters.readonly`.

Google API Services User Data Policy: https://developers.google.com/terms/api-services-user-data-policy
Google Privacy Policy: https://policies.google.com/privacy
Google Terms of Service: https://policies.google.com/terms

No Notch/Top Notch cloud server is used by v0.4 for Search Console synchronization.

== Privacy ==

Site audit and keyword data remain in the local WordPress database. When Search Console is connected, the OAuth Client ID, Client Secret, Google refresh token, selected property and synced Search Analytics rows are also stored locally in WordPress options/tables. Administrators should restrict database access and backups accordingly.

By default, audit data is preserved if the plugin is uninstalled. Administrators can enable Delete data on uninstall under AI SEO Tool > Setup & Settings before uninstalling.

== Installation ==

1. Upload and activate the plugin.
2. Open AI SEO Tool.
3. Run Site Audit.
4. Import keyword research.
5. Review Keyword Decisions, Pillars and Clusters.
6. Optional: open Search Console, create/configure Google OAuth credentials, connect Google, choose a property and sync performance data.

== Frequently Asked Questions ==

= Does it edit or publish my content? =

No. The audit and recommendation engine is read-only with respect to WordPress posts, pages, products, schedules, URLs and SEO metadata.

= Does Search Console integration change anything in Search Console? =

No. It requests the read-only Search Console scope.

= Does it provide exact Google keyword difficulty? =

No. WordPress and Search Console data do not provide a universal live keyword-difficulty score. Import third-party KD/volume data if you want those fields included in prioritization.

= Why can a Search Console query show more than one page? =

That can indicate cannibalization, but it can also be normal. The plugin labels these as review signals rather than automatically recommending redirects, deletion or consolidation.

= Can it be used on any niche? =

Yes. No niche or website is hard-coded.

== Changelog ==

= 0.4.2 =
* Renamed the public product to TopNotch AI SEO Tool while preserving the proven NCI internal identifiers, database tables, option keys and upgrade path for compatibility.
* Updated visible admin branding and menu labels.
* Preserved the existing product/documentation URL and Google Search Console behavior.


= 0.4.1 =
* Prepared the public WordPress.org release metadata and support links.
* Updated the product URI to the official Notch Content Intelligence page.
* Added the Top Notch Agency LLP author URI.
* Updated compatibility metadata for WordPress 7.1.
* Tightened the directory short description and tag set.
* No audit, scoring, Search Console, import, export, or uninstall behavior was removed.

= 0.4.0 =
* Added opt-in Google OAuth 2.0 connection using the Search Console read-only scope.
* Added Search Console property discovery and selection.
* Added 28/90/180/365-day Search Analytics sync grouped by query and page.
* Added local GSC performance table and query aggregation into keyword metrics.
* Added multi-page query cannibalization review report.
* Search Console impressions/clicks/average position now feed opportunity scoring.
* Added explicit external-service and privacy documentation.

= 0.3.0 =
* Added public-release setup and privacy controls.
* Added CSV exports for decisions and pillars.
* Added intent-aware matching and body-term analysis.
* Added first-run workflow and optional clean uninstall.
* Hardened keyword upload validation.
* Confirmed site-agnostic custom-post-type scanning.

= 0.2.0 =
* Added explicit Already Exists / Ignore / Merge / Write recommendations.
* Added proposed-pillar and long-tail cluster decisions.
* Generalized scanning beyond site-specific rules.
