NeuronWriter Content Workflow

NeuronWriter is an optimization step inside the PID-owned research workflow. It does not replace keyword research, content review, or the WordPress sync pipeline. The human/AI research synthesis is stored in research/<PID>/; NeuronWriter's tool artifacts remain in neuronwriter/.

idea
  -> keyword research
  -> create content PID and research/<PID>/
  -> human or AI research
  -> NeuronWriter brief
  -> draft
  -> NeuronWriter evaluation
  -> human review
  -> scheduled
  -> published

What Each Artifact Means

Brief

The brief is created before drafting. It records the SERP information that should guide the author. It is an input to the dedicated PID research file, not the final writing brief by itself:

• Search intent and dominant content type
• Recommended title, H1, H2, and description terms
• Essential and recommended topical terms
• PAA and content questions
• Entities and competitor summaries
• Word-count and readability benchmarks

Stored at:

neuronwriter/briefs/<PID>.md

Evaluation

The evaluation is created after a Markdown draft exists. It records the score, timestamp, and API response returned when the draft is evaluated.

Stored at:

neuronwriter/evaluations/<PID>.json

The evaluation does not automatically rewrite the draft or block publishing. A human decides whether to revise the content and mark the optimization status approved.

Inventory Contract

content-inventory.csv carries only the fields needed to find and control the workflow:

Column	Purpose
NeuronWriter Query ID	Identifies the NeuronWriter analysis
NeuronWriter Brief Path	Links to the Markdown brief
NeuronWriter Status	Empty / not_started / brief_ready / evaluated / approved / failed

Do not add score, project ID, evaluation path, or timestamps to the CSV. Those values belong in the brief frontmatter or evaluation JSON. The final human/AI synthesis belongs in research/<PID>/research.md, linked by the inventory's Research Path column.

Commands

Run from the local control mirror:

cd /home/rezriz/github/seo-content/web-project/id86.net

# Confirm the request without using the API or quota
python3 scripts/neuronwriter.py brief \
  --pid DEV-000003 \
  --project PROJECT_ID \
  --dry-run

# List projects (requires NEURON_API_KEY)
python3 scripts/neuronwriter.py projects

# Create a brief and poll until NeuronWriter is ready
python3 scripts/neuronwriter.py brief \
  --pid DEV-000003 \
  --project PROJECT_ID \
  --keyword "tmux split pane"

# Evaluate the existing Markdown draft (requires markdown2 in the local Python environment)
python3 scripts/neuronwriter.py evaluate --pid DEV-000003

# Or evaluate an already-rendered HTML draft without markdown2
python3 scripts/neuronwriter.py evaluate --pid DEV-000003 \
  --html-file /path/to/draft.html

The API key is read from NEURON_API_KEY or ~/.ssh/neuronwriter/.env. Keep that file outside Git with mode 600.

Operating Rules

• Use SpyFu or another keyword source for volume, difficulty, and opportunity.
• Use NeuronWriter for SERP structure and topical coverage.
• Treat recommended terms as guidance; never force exact usage counts.
• Do not automatically overwrite Title, Description, Markdown body, or publishing Status.
• Do not make a low NeuronWriter score an automatic publishing blocker.
• NeuronWriter calls consume analysis quota; run them for confirmed opportunities.
• The WordPress sync.py path remains independent from NeuronWriter.

Failure Handling

If a query fails or times out, set NeuronWriter Status to failed, preserve the error in the command output or evaluation artifact, and fix or retry manually. Do not move the content lifecycle Status backward automatically.

Security

Never store an API key in this documentation, a CSV, a command-line argument, or a Markdown brief. Any previously exposed key must be revoked and replaced before using the workflow.