=== Benabis Host Kit: Transcript Importer ===

Adds cleaned episode transcripts and key takeaways to podcast episode posts.

== How it works ==

1. Prepare transcripts in the High on Healthy Tracker or Host Kit. The Tracker saves
   each one to a Google Drive folder; Host Kit downloads an import file.
2. Version 1.3: the plugin watches that Google Drive folder and imports every new or
   changed .json file in it each hour (Host Kit > Podcast transcripts > Watch a Google
   Drive folder). You can still upload a file by hand.
3. Each transcript attaches to its episode post right away if the post exists.
   If the episode is not published yet, the transcript waits in the queue and
   attaches automatically when the feed creates the post (checked when the post
   is saved, two minutes later, and every hour).

Version 1.1: the transcript is written into the end of the episode post's own
content, between <!-- sti:start --> and <!-- sti:end --> markers, as "Key
takeaways", links to the episode's topic pages and idea article, and a
collapsible full transcript at the anchor #transcript. Edit anything above the
markers freely. If the feed rewrites the post, the block is added back
automatically.

Google Drive setup (once): in Google Cloud Console create a project, enable the
Google Drive API, create a service account, add a JSON key and download it. Paste
the key and the folder link into the plugin, then share the folder with the
service account's address as a Viewer. The plugin requests read-only access.

Topic pages: each entry carries one to three topics. Version 1.2: each site has
its own topics. Host Kit builds them from the site's content (copy it from
Host Kit > Podcast transcripts > Site content for Host Kit) and sends each topic's
name, introduction and related pages in the import file. A changed introduction
replaces the one on the topic page only if you have not edited it. The built-in
High on Healthy topics are used on memores.me only.
 The first time a published
episode has a topic, a page is created under /podcast-topics/ with an
introduction you can edit, plus an automatic section (between sti-hub markers)
listing the related assessments, every episode, the idea articles and related
topics. An index page at /podcast-topics/ lists all topics. A topic page with no
episodes left goes back to draft.

Idea articles: each entry can carry one short article on the episode's best
idea. It is created when the episode attaches, as a draft by default (or
published, per Settings), in the Ideas category, linked to the episode and its
topics. Publishing it adds "The big idea" link to the episode and lists it on
the topic pages. Articles you have edited in WordPress are never overwritten by
a re-import.

Matching: an exact post slug from the import file wins. Otherwise the earliest
published post in the episode category, dated from the day before the recording
to 120 days after it, that names the guest in its title or text.

Guest links (1.6): each guest's own website and profiles, shown on the episode as "Find <guest>: ..."
under the key takeaways, with the first mention in the transcript linked too. They are found in the
transcript, written ("nickjonsson.com") or spoken ("nick jonsson dot com"), and in the import file's
"guest_links". Each link is opened to check it works and mentions the guest, then waits for review
under Host Kit > Guest links. Existing episodes can be checked from that screen.

Links: internal links that do not resolve to a live page are turned back into
plain text. External links get rel="noopener".

Re-importing an entry with the same id replaces it, including on the post it is
already attached to.

== Import file format (version 4; versions 1 to 3 still work) ==

{
  "format": "podcast-transcript-import",
  "version": 4,
  "source": "High on Healthy Tracker",
  "generated": "2026-10-08T21:00:00Z",
  "topics": [                                            (version 3, optional)
    {"name": "Digital Habits", "intro": "...", "links": [{"name": "Free quiz", "url": "https://..."}]}
  ],
  "entries": [
    {
      "id": "Google Drive file id or another stable id",
      "guest": "Gloria Mark",
      "recorded": "2026-09-30",
      "episode_title": "Who Owns Your Attention? ...",   (optional)
      "post_slug": "who-owns-your-attention-...",        (optional, best match)
      "takeaways": ["...", "..."],                       (optional)
      "topics": ["Attention and Focus"],                 (version 2, optional, up to 3)
      "idea": {"title": "...", "question": "...", "html": "<p>...</p>"},  (version 2, optional)
      "seo": {"title": "...", "description": "..."},     (version 4, optional)
      "guest_links": [{"url": "https://...", "label": "nickjonsson.com", "quote": "..."}],  (version 4, optional)
      "transcript_html": "<h3>00:05:00</h3><p><strong>Name:</strong> ...</p>"
    }
  ]
}

Allowed transcript HTML: p, h3, h4, strong, em, br, ul, ol, li, a[href].

== Changelog ==

1.12.1: An approved transcript whose episode is older than the catch-up window, and missing from the site, now gets its episode post created from the podcast feed, so it can attach. Other older episodes are left alone.
1.12.0: Approve once. A transcript you approve (or send) in Host Kit attaches as soon as its episode post exists, without a second approval in this site's review list (Settings, "New transcripts"; on by default). Duplicate episode posts are cleaned up: when the feed importer and this plugin both create a post for the same episode, the copy without the transcript goes to the trash (checked a few minutes after any new post, every hour and on every website update). A transcript whose episode post was deleted or trashed goes back to waiting and attaches to the episode's current post. New status address for Host Kit (sti/v1/status): what is waiting, what is in the review list, and the recent activity log.
1.8.0: Host Kit on benabis.com can send prepared transcripts straight to the site and read its topic and episode pages, with the site's remote access key.
1.7.1: Updates install on benabis.com itself. That site serves the releases, and its host refuses a site's downloads from its own address ("Download failed. Service unavailable"); there the update is now read from the release file on disk, checked against the published checksum.
1.7.0: Works for any podcast. New sites start blank: add the RSS feed under Settings and the plugin fills
       in the show name and finds the episode category. Sites updating from an older version keep their
       current settings. Episodes, idea articles and topic pages get a search title and description
       (155 characters or fewer), from the import file's "seo" field or built from the page. With Benabis
       SEO Tools active, those go into its own title and description fields where empty and this plugin
       prints no tags; with another SEO plugin active, its empty descriptions are filled instead.

1.6.0: Guest links. Finds each guest's website in the transcript (written or spoken) and in the
       import file, checks it, and after you approve it under Host Kit > Guest links shows it on the
       episode. Each site now gets its own remote access key and sets its own podcast feed address.

1.5.2: Renamed Benabis Host Kit. Its pages move from the Tools menu to a new "Host Kit" menu in
       the sidebar (old links still work). Updates now come from benabis.com, so no GitHub token
       is needed; the token setting is gone and any saved token is deleted.
1.5.1: Works with a private update repository: paste a read-only GitHub token under Host Kit >
       Podcast transcripts > Automation.
1.5.0: Updates itself. New versions published to github.com/rzwicky-apps/benabis-wordpress-plugins
       install automatically, or show a notice when automatic updates are turned off (Host Kit >
       Podcast transcripts > Automation). "Check for updates" on the Plugins screen checks now.
1.4.2: Green "New" flags on episodes published in the last 7 days and on their topics. Automation
       settings: website update schedule, run on new episode posts, when Drive is checked, automatic
       topic-page rebuilds. Topic names with commas are no longer split; earlier splits repaired.
1.4.0: "Update the website now": creates recent episode posts missing from the site (for example
       back-dated ones), imports from Drive and attaches transcripts. Remote run for the Tracker.
