BLUEPRINT.md 20 KB

STRATA blog: compact SEO_OPT adaptation

Status: approved local implementation of three English destination guides, 2026-10-09; no push or deployment authority. Target: text.skin, Gogs jerry/web-ui, Next.js 14.1.0. This document is a workflow specification, not evidence that publication, approval, indexing, or growth has happened.

Scope and durable assets

The framework supports English, German, French, Spanish, Italian and Portuguese; smaller languages remain deferred. Keyword and service-scope research is complete for this first decision. The user approved three English appointment guides for Ireland residents: Netherlands first, Greece and Denmark. No-slots checks and document preparation remain sections within each guide. Other languages and extra topics are conditional future work, not a launch quota. The old Italy drafts are preserved only in docs/editorial/archive/italy-provisional-2026-10-08.json, excluded from all routes and metadata. The report supporting this scope distinguishes Ireland Google Ads estimates, a Dublin SERP snapshot, missing data and population background; none proves traffic, conversion, or ranking outcomes.

Use the article collection as the content inventory; approved-inventory.json is only the exact release allowlist for the approved IDs/locales/slugs, not a second task backlog. Keep this one blueprint, production content, code/tests, and normal Git/review receipts. Do not add a second backlog, daily report directories, raw response archives, per-article rule files, a scheduler, or an agent framework. No backend, booking automation, account, payment or credential work is included. No push, deployment, external publication, or Google submission is authorized by this plan.

Provenance: actual previous design, not a generic replacement

Read-only sources checked against zhangweijp/soulname-v2 at c4f3f7c on 2026-10-08:

Source Adopt / adapt / do not reuse
seo_opt/SKILL.md, blob 3bf67384309b58ebda09e590ba2e083221d970bb Adopt preflight, scoped permission checks, useful complete drafts, same-version review and separate outcomes. Adapt the entry checklist to this repository. Do not reuse SoulName's naming columns, quotas, dates or scheduling authority.
seo_opt/policy.json, blob 04a61c5cc55e0f7e10d36063311bc998d3558d4f Adopt explicit boundaries and no automatic publication. Do not copy its domain, project/property IDs, seven-country filters, budget authority, automation ID or runtime settings.
seo_opt/OPERATIONS.md, blob df75f85d0bfb0e031b2a4668ac680ecc0b84de4c Adopt evidence → diagnosis → bounded action → verification → measured learning, unknown-write reconciliation, minimal records and separate live/submitted/indexed facts. Adapt to a manual, local draft workflow with no runtime ledger.
seo_opt/CONTENT.md, blob db6817be494b05d240655c0266e1e391070b41df Adopt native-language intent, honest title, reader benefit, complete same-version reading and source attribution. Replace naming research with current consular primary sources and jurisdiction-specific boundaries.

The local reference checkout was soulname-404-i18n-3c313c6/seo_opt/; its dirty working tree was not treated as proof of current main. Both seo/BLUEPRINT.md and seo_opt/BLUEPRINT.md returned 404 at the checked GitHub ref. The four current documents above are the verified design reference; no historical blueprint content is invented. No SoulName state.json, active run, runtime or automation is copied or executed.

Tool roles carry over as a design only: OpenSEO = search intelligence; DispatchSEO = editorial/queue state; Git = versioned implementation and authorized publication. Their connection to text.skin has not been established. Existing source reads and repository files suffice for the current draft. A future integration needs a verified target project, permissions and a successful scoped read; “connected” alone does not prove data access. No tool installation or paid research is implied.

Discovery gate: evidence before a content backlog

The latest data-first direction supersedes the earlier proposal of three Italy topics multiplied into 18 pages. Start with keyword discovery following the user's requested 哥飞 approach, grounded in actual primary-source guidance researched separately; do not attribute an invented checklist to him. Confirm service origin/destination coverage first. Then gather native-language seed queries, related questions and actual SERP examples for the confirmed services. Record source/tool, geography, language, date, visible metrics and limitations. Distinguish measured search demand from plausible reader needs, keyword suggestions and official factual evidence.

Compare demand, intent, competition and fit to the real product before choosing topics. Keep missing volume/difficulty/market coverage explicitly unknown; a connected tool or an official visa page does not prove keyword opportunity. Deduplicate intent, identify what a genuinely useful page adds, and present a small ranked recommendation with evidence and uncertainties for approval. Only after that decision should the existing article inventory become an approved content backlog and full drafts/localizations resume. Do not run new tools, buy data, or expand permissions merely because a workflow mentions them. The root task owns current discovery; this checkpoint creates no research executor or new ledger.

Preflight and working loop

Before each change: identify the repository/branch and current diff, actual article version, owner of each file, existing same-intent articles and unfinished reviews, current environment/domain, and authorized action. Preserve others' work. Check unknown external outcomes before retrying; do not recreate a task to bypass an unresolved write. State a concrete completion condition. Independent authorized work can continue around a blocker, but translations and additional topics remain outside the approved three-English-guide scope.

Step What / why / how Smallest evidence or output
Observe Confirm actual service scope, then inspect keyword/SERP evidence and existing inventory before committing topics; official sources verify facts, not search demand. Use scoped analytics only if actually available. Article ID, locale, question, source URLs, read date and coverage/unknowns.
Validate Check source authority, jurisdiction, date and whether each claim follows from the source. Recheck expired or changed requirements. Supported claims and unresolved claims; never convert an unread source, empty result or error into proof.
Diagnose Identify the specific content/technical gap. Distinguish eligibility, booking scarcity, missing documents, and site defects. Reproduction or reader gap; no claimed traffic decline without comparable data.
Decide Prioritize blockers and already-started useful work. Deduplicate same intent; keep a topic within a useful guide unless separate intent warrants another page. Continue, revise, defer or stop, with a short reason.
Plan Fix scope, files, exact article version, checks, review responsibility and rollback before editing. Review description tied to the current diff; no parallel plan file.
Execute Write complete native-language prose and implement the approved local changes. Keep source-supported steps usable without a product CTA. Current full article and related implementation diff.
Verify Read the entire current article, verify claims and title payoff, then run mechanical and rendered-page checks. Review a changed version again. Editorial judgment with concrete passages plus actual command/exit-code and browser results; mark unrun checks.
Measure Only after an authorized release: verify actual live version, then separately observe search and business outcomes. Same-scope evidence or blocked/inconclusive status, never invented zeroes.
Learn Fix the current defect first; add only a reusable preventative rule/test at its earliest cause. One concise rationale in the normal review/Git history; replay is not proof of future effectiveness.
Clean Remove only owned temporary materials; retain production content, necessary citations, pending blockers and normal review receipts. Compact completion note: delivered, verified, blocked, next decision.

Content gate for the approved first cohort

Each intent family shares a stable article ID across locales. The article collection is the sole inventory; published is a production renderer inclusion flag, not user approval or a real-world publication receipt. The three current English records have passed independent editorial review and have published:true solely for local release-candidate verification. This is not remote publication authority; the default indexing gate remains off. Local review mode deliberately exposes draft routes with noindex; noindex is not access control and the review build must not be publicly deployed. reviewedAt is a genuine review date, not a claim that all sources were updated that day. Do not bump it without rechecking the content.

The approved guides must solve three distinct reader tasks:

  1. Netherlands: find the official VFS Dublin route, prepare the application, and understand availability checks. Prominently preserve NetherlandsWorldwide’s advice to book personally and avoid intermediaries; do not imply official approval of an automatic-booking service.
  2. Greece: select the correct Embassy-linked category, understand the verified calendar workflow and obtain appointment confirmation. Do not substitute a third-party search result for the Embassy’s linked route.
  3. Denmark: choose the right destination, tourist category and Ireland submission route, keeping application registration separate from appointment booking. Do not transplant business-visa or another country’s procedure.

The official booking CTA is article-specific. Source current facts, explain no availability and preparation within each guide, and do not manufacture separate thin pages. Related-country links need a reader reason; an empty related list is acceptable.

For every locale: formulate the actual reader question in that language, compare two honest title options during review, choose one whose promises the article delivers, and review the full native-language version. Translation presence is not proof of language quality. Unverified query volume remains unverified; do not manufacture keywords or call English-first copy native research. Read the opening, practical steps and conclusion as a first-time reader. A bibliography, word count, headings and a passing build cannot replace this review.

Keep official source URLs beside the claims they support and in sources; re-open them before final editorial approval and before any later release. Distinguish current rules from interpretation and product statements. If a consequential source is unavailable or contradictory, narrow the claim or block it; do not silently infer an answer. Product facts supplied by the owner are not evidence that a consulate authorizes that service.

STRATA's described product can book on a user's behalf. Do not rewrite it as notifications-only to sidestep the issue. Each destination’s actual official guidance must be represented accurately, including the Netherlands recommendation to book personally and avoid intermediaries. Do not generalize old Italy-only requirements across countries. Clearly identify STRATA as an independent third party, without embassy affiliation, guaranteed appointments, guaranteed visas, or implied permission/compliance. The user must resolve any product/official-rule conflict before promotional claims about that use are approved. Educational guides can still give complete official self-service guidance. No misleading workaround instructions.

Implementation map and ordered handoff

Owner / step Existing implementation targets Acceptance
Discovery owner, then content author after approval src/content/blog/articles.json, contract src/lib/blog/types.ts The current allowlist is three English Netherlands/Greece/Denmark guides. Archived Italy examples never enter the active collection. Approved records need shared IDs where genuinely equivalent, unique locale/slug pairs, real sources, accurate review dates and valid related IDs.
Blog implementation: load only intended records and render routes src/lib/blog/data.ts, src/components/blog/{BlogShell,BlogViews}.tsx; src/app/(blog-en)/blogs/; src/app/(blog-localized)/[locale]/blogs/; blog components /blogs and /{de,fr,es,it,pt}/blogs, with article detail routes. Unknown locale/slug must not render an article. With indexing enabled, drafts must be excluded from routes, navigation, alternatives and sitemap. With indexing disabled, draft routes are intentionally reviewable.
Blog implementation: localized presentation src/lib/blog/translations.ts, route layouts and components Correct html lang, complete UI copy and article text in each locale; links preserve intended language. No missing translation keys, raw namespace keys or accidental app locale coupling.
Blog implementation: metadata and crawl policy src/lib/blog/metadata.ts, src/app/sitemap.ts, src/app/robots.ts One canonical per page, reciprocal actual translations, consistent JSON-LD, safe default indexing gate, accurate sitemap.
Reviewer: same-version review and technical verification Current complete content + rendered build + normal test receipts Editorial verdict and technical results separately recorded against the exact diff/commit or hashes. Later edits invalidate affected review.
Release owner: future authorized delivery only Normal Git/release process Explicit current-version approval and publication authority, then verified deployment and live rendered URLs. Not part of this draft delivery.

The code owner owns implementation and test commands; this document does not claim they have passed. Do not start another content copy or parallel implementation. Resolve review corrections in the existing articles/code.

Mechanical gate recipe

Run from the target checkout, capture actual results in the normal review, and rerun affected checks after corrections:

  • Inventory/schema checks: only the six allowed locales; coverage exactly matches the approved inventory; stable unique slugs; nonempty bodies/descriptions; valid dates, HTTPS source URLs, and related IDs; language selector targets exist. Completeness checks are structural, not an editorial verdict.
  • npm run lint, npx tsc --noEmit, and npm run build, and node scripts/check-blog.mjs for content and SEO fixtures. A pre-existing failure is reported with scope; never label an unrun or failed stage passed.
  • Default build with BLOG_INDEXING_ENABLED absent/false: editorial previews are noindex, sitemap empty, and robots permits crawling so crawlers can see noindex. Draft routes are intentionally exposed in this local review mode. Noindex is not confidentiality or access control; do not deploy this preview publicly.
  • Use node scripts/check-blog.mjs in-memory published fixtures to test release mechanics without changing real draft flags. In an isolated local verification build only, set BLOG_INDEXING_ENABLED=true and rebuild to verify real drafts are excluded from routes, navigation, alternatives and sitemap; then restore the default preview build. Run BLOG_INDEXING_ENABLED=true node scripts/check-blog.mjs --release only after the content reviewer approves the complete current records. It checks the exact approved inventory, not three pages in every language. Keep real flags false until editorial approval; passing this gate establishes only local release eligibility, never deployment authority. Later, before an authorized release, this check and the release build must pass and the prospective canonical URLs and sitemap must be inspected. Changing an environment variable without rebuilding does not update generated metadata. This test does not authorize production enablement.
  • Inspect rendered HTTP headers and HTML for every locale index and article. Canonical origin is exactly https://text.skin; no tunnel, localhost, copied SoulName domain or tracking query. HTML and HTTP Link alternatives must not contradict or duplicate one another. Inspect a query-bearing URL too. No pagination is introduced in this foundation; if added later, define its own canonical/translation mapping instead of assuming page-number equivalence.
  • hreflang advertises only actual matching article editions, with self and reciprocal links; x-default uses the actual English target. For the indexing-enabled test, every target is a canonical sitemap member and returns the matching locale/content. No nonexistent “translation” is generated by pathname substitution.
  • Check title, description, html lang, canonical, Open Graph URL, Article/Breadcrumb JSON-LD and visible source/review labels against the same article record. Unknown routes return real not-found behavior. Test direct loads and locale switching; inspect desktop and narrow-screen readability, focus/links, source navigation and repeated navigation without calling a screenshot-only review comprehensive.

Regression lessons from SoulName are prevention targets, not a claim that this site already has those faults: automatic HTTP hreflang can conflict with per-page HTML alternatives; query-bearing archive pages cannot blindly inherit root canonicals or translation assumptions; drafts need explicit exclusion/noindex controls; route rendering can fail when required translation namespaces are omitted. Relevant prior code/reference paths include src/proxy.ts, src/tests/i18n/public-metadata.test.ts, src/i18n/messages.ts and src/tests/i18n/messages.test.ts in SoulName. Keep equivalent checks in this project's existing validation instead of transplanting its middleware, namespaces, tests or framework version.

Release and outcome gates remain separate

Use the normal review/release record for each status and its evidence; do not add a runtime state file merely to represent these concepts:

  1. Editorial review: current complete locale text read, source claims and native phrasing checked. An author's self-review is not an independent review.
  2. User approval: explicit approval of the identified current version and requested action. A content review is not deployment authority.
  3. Technical verification: actual tests/build/render results for that version; failures and untested conditions remain visible.
  4. Published/live: after separate authorization, the intended version is confirmed on the real production URL. A local build, repository push or deployment success alone is insufficient.
  5. Submitted: only after authorization, an actual Search Console submission receipt. No submission exists in this phase.
  6. Indexed: actual URL Inspection indexing result and selected canonical agree with the intended page. HTTP 200, a sitemap, Live Test and site: search do not prove this. Pending, rejected and unknown stay separate.
  7. Search outcome: comparable final GSC windows with exact page, country, device and search type; calculate CTR from clicks/impressions. Ireland residence is the initial reader context, not automatic proof of a search country or language market. Record the real filter and timezone. No baseline means a new-page observation, not a fabricated zero-history improvement.
  8. Commercial outcome: actual attributable product results, if legitimately available, separate from clicks or rankings. No causal lift or visa/appointment success guarantee follows from SEO checks.

For a future experiment, fix baseline and observation windows, minimum useful sample and guardrails before release. Do not shorten the window after seeing results. Empty, failed, not-yet-final, low-sample and unmeasured are different states. If no analytics integration exists, say measurement is blocked; the current local deliverable can still be reviewed. No automatic scheduling is established by this document.