nick/PlotDirector
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
PlotDirector/AGENTS.md

8.7 KiB
Raw Blame History

PlotDirector Codex Operations Guide

This repository is the PlotDirector ASP.NET Core application. Use this file as the first stop for operational knowledge that is not obvious from source.

Environment Architecture

  • Main repo path: /srv/repos/PlotDirector.
  • Web app project: PlotLine/PlotLine.csproj.
  • Test project: PlotLine.Tests/PlotLine.Tests.csproj.
  • Solution file: PlotLine.slnx.
  • Word add-in project: PlotDirector.WordCompanion/.
  • Development site host files: /srv/apps/plotdirector-dev/current.
  • Development release archive: /srv/apps/plotdirector-dev/releases/.
  • Development systemd service: plotdirector-dev.
  • Service working directory: /srv/apps/plotdirector-dev/current.
  • Service environment file: /etc/plotdirector/plotdirector.env.
  • The dev app listens locally on http://127.0.0.1:5050 behind nginx as https://dev.plotdirector.com/.

Database

  • Production-style dev database name: PlotDirector_Development.
  • Older/local default database name in appsettings may be PlotLine; do not assume that is the effective dev database.
  • Runtime connection details come from /etc/plotdirector/plotdirector.env, key ConnectionStrings__DefaultConnection.
  • Do not print, copy, or commit connection strings, passwords, API keys, SMTP secrets, Stripe secrets, or OpenAI keys.
  • The SQL Server is reachable from the app host using the environment-file connection string. If a one-off SQL runner is needed, read the env file safely without shell-evaluating values:
conn=""
while IFS= read -r line; do
  case "$line" in
    ConnectionStrings__DefaultConnection=*) conn="${line#ConnectionStrings__DefaultConnection=}" ;;
  esac
done < /etc/plotdirector/plotdirector.env
export PLOT_DIRECTOR_SQL_CONNECTION="$conn"
  • Do not use source /etc/plotdirector/plotdirector.env; unquoted values with spaces or special characters can break the shell and leak confusion into the task.
  • Use stored procedures for application database access. Do not add inline SQL in application code.
  • Old SQL scripts are immutable. Never edit an existing numbered script to fix a live schema issue; add a new forward-only script.
  • Before restarting/deploying during Story Intelligence work, check there are no active runs in StoryIntelligenceRuns, StoryIntelligenceJobs, or WholeBookPlotSynthesisRuns.
  • Do not restore, reset, or overwrite PlotDirector_Development unless the user explicitly asks and the target backup has been verified. Restore backups only to disposable verification databases first.

SQL Migration Procedure

  • Number new scripts under PlotLine/Sql/ using the next available prefix, for example 175_...sql.
  • Scripts should be idempotent where practical: guard table/column/index creation with existence checks and use CREATE OR ALTER PROCEDURE.
  • Apply database changes to dev deliberately and capture the script path in the final response.
  • After applying SQL, run a smoke query that confirms the expected tables/procedures/columns exist and that the connection reports PlotDirector_Development.
  • Permanent delete paths have historically exposed missing cascade/cleanup dependencies. When adding tables that reference projects, books, chapters, scenes, characters, candidates, or runs, design deletion behaviour intentionally.

Build And Test

  • Full test gate:
dotnet run --project PlotLine.Tests/PlotLine.Tests.csproj
  • Build gate:
dotnet build PlotLine.slnx
  • Publish gate:
dotnet publish PlotLine/PlotLine.csproj -c Release -o /tmp/plotdirector-dev-publish-<commit>-<timestamp>
  • Known quirk: running build and tests in parallel can cause static web asset cache file locks, especially around *.staticwebassets*.json or rjsmrazor.dswa.cache.json. Run build/test serially when verifying.
  • Prefer rg/rg --files for repository searches.

Running Locally

  • From /srv/repos/PlotDirector, run:
dotnet run --project PlotLine/PlotLine.csproj
  • For local database/API work, provide configuration through environment variables, user secrets, or a safe local appsettings override. Do not rely on secrets committed in appsettings, and do not add new secrets to source.
  • The deployed dev service uses /etc/plotdirector/plotdirector.env; local terminal runs do not automatically use that file unless you explicitly provide equivalent environment variables.

Development Deployment

Use the existing physical-directory deployment pattern. current is a real directory, not a symlink.

  1. Confirm the commit to deploy:
git status --short --branch
git log -1 --oneline
  1. Confirm no active Story Intelligence work is running before restart.
  2. Publish to a fresh temp folder:
release="<shortsha>-$(date -u +%Y%m%d%H%M%S)"
publish_dir="/tmp/plotdirector-dev-publish-$release"
release_dir="/srv/apps/plotdirector-dev/releases/$release"
backup_dir="/srv/apps/plotdirector-dev/current-before-$release"
dotnet publish PlotLine/PlotLine.csproj -c Release -o "$publish_dir"
  1. Install the release:
sudo mkdir -p "$release_dir"
sudo cp -a "$publish_dir"/. "$release_dir"/
sudo chown -R plotdirector:plotdirector "$release_dir"
sudo cp -a /srv/apps/plotdirector-dev/current "$backup_dir"
sudo chown -R plotdirector:plotdirector "$backup_dir"
sudo rsync -a --delete "$release_dir"/ /srv/apps/plotdirector-dev/current/
sudo chown -R plotdirector:plotdirector /srv/apps/plotdirector-dev/current
sudo systemctl restart plotdirector-dev
  1. Verify:
systemctl is-active plotdirector-dev
systemctl status plotdirector-dev --no-pager -n 30
curl -k -L --max-time 20 -o /tmp/pd-dev-home.html -w 'http_code=%{http_code}\nfinal_url=%{url_effective}\nbytes=%{size_download}\n' https://dev.plotdirector.com/
sudo stat -c 'CurrentDll=%n %y %s bytes' /srv/apps/plotdirector-dev/current/PlotLine.dll
  • A HEAD request to the dev site may return 405; use GET with curl -L for the real smoke check.
  • Keep the release folder and current-before backup named with the deployed short SHA and UTC timestamp for traceability.

Project Structure

  • PlotLine/Controllers/: MVC controllers.
  • PlotLine/Views/: Razor views.
  • PlotLine/Services/: application services, Story Intelligence workers, OpenAI integration, import/onboarding flow.
  • PlotLine/Data/: repositories and database access.
  • PlotLine/Models/: domain and DTO models.
  • PlotLine/ViewModels/: UI view models.
  • PlotLine/Hubs/: SignalR hubs.
  • PlotLine/wwwroot/: static CSS/JS/assets.
  • PlotLine/Sql/: forward-only SQL migration scripts and stored procedure definitions.
  • PlotLine.Tests/Program.cs: lightweight integration/regression test harness.
  • docs/ and Docs/: project documentation stores; check both before creating new documentation.

Story Intelligence Conventions

  • PlotDirector must work for arbitrary books and authors. Do not add production special cases for Alpha Flame or any other manuscript-specific names, places, vehicles, objects, or relationships.
  • Manuscript-specific examples may appear in regression fixtures only, and tests should include unrelated examples so production code cannot pass by recognising one fixture.
  • Use generic evidence for significance: recurrence, scene/chapter presence, ownership, narrative prominence, title presence, knowledge significance, and participation in important events.
  • Relationship classification must use generic interaction evidence and configured relationship types, not character-specific rules.
  • Character/alias resolution should use canonical identities, aliases, and evidence rather than book-specific names.
  • Scene manuscript text in SceneManuscriptSources is the durable source for canonical scene analysis.
  • Core import and Story Intelligence are separate phases. Do not reintroduce the old visualisation/replay workflow as part of production import.
  • Whole-book plot synthesis should happen after character resolution and should not add another per-scene AI pass.
  • If prompt/source text is too large, fail the specific synthesis job clearly rather than silently truncating manuscript text.

Operational Safety

  • Avoid destructive git commands such as git reset --hard or git checkout -- unless the user explicitly asks.
  • The worktree may include user changes. Inspect before editing and do not revert unrelated changes.
  • Do not deploy while an import or Story Intelligence analysis is active unless the user explicitly accepts the interruption.
  • Do not modify current database state for read-only investigation tasks.
  • Do not apply SQL during read-only audit tasks.
  • Use disposable verification databases for restore checks and drop them afterwards unless instructed otherwise.
  • Keep deployment and SQL notes concise in final responses: commit, SQL script, tests, deployed release, service status, and any residual risks.