From 7d9e04dcfafd7325d268f379b064c46fee7e582d Mon Sep 17 00:00:00 2001
From: bnz183 <bnz183@users.noreply.github.com>
Date: Tue, 9 Jun 2026 12:19:01 +0200
Subject: [PATCH] GitHub API polish and early Studio UI improvements

---
 README.md                                     |   2 +
 apps/studio/server/media.ts                   |   6 +-
 apps/studio/server/posts.ts                   |   7 +-
 apps/studio/server/publish.ts                 |   3 +-
 apps/studio/src/App.tsx                       |  41 +--
 apps/studio/src/components/AdapterStatus.tsx  |  23 +-
 .../studio/src/components/ArticlePipeline.tsx |  70 +++--
 .../studio/src/components/AstroMdxPreview.tsx |  43 ++-
 apps/studio/src/components/CommandBar.tsx     |   6 +-
 .../studio/src/components/EditorWorkspace.tsx |   4 +-
 .../src/components/FrontmatterInspector.tsx   |  22 +-
 apps/studio/src/components/LoginScreen.tsx    |  29 ++-
 apps/studio/src/components/MediaDropzone.tsx  |  81 ++++--
 apps/studio/src/components/PublishGate.tsx    |  72 +++--
 apps/studio/src/index.css                     | 127 +++++++--
 apps/studio/src/lib/media.ts                  |   6 +-
 apps/studio/src/lib/posts.ts                  |  11 +-
 apps/studio/src/lib/publish.ts                |   6 +-
 docs/configuration.md                         |   2 +
 docs/github-publishing.md                     |  44 +++-
 docs/project-status.md                        |  12 +-
 package.json                                  |   2 +-
 packages/github-publisher/package.json        |   4 +-
 .../github-publisher/src/githubErrors.test.ts |  92 +++++++
 packages/github-publisher/src/githubErrors.ts | 177 +++++++++++++
 .../github-publisher/src/githubPaths.test.ts  |  16 ++
 packages/github-publisher/src/githubPaths.ts  |  11 +
 .../github-publisher/src/githubPublisher.ts   | 245 ++++++++++++------
 packages/github-publisher/src/index.ts        |   9 +
 pnpm-lock.yaml                                |   3 +
 30 files changed, 935 insertions(+), 241 deletions(-)
 create mode 100644 packages/github-publisher/src/githubErrors.test.ts
 create mode 100644 packages/github-publisher/src/githubErrors.ts
 create mode 100644 packages/github-publisher/src/githubPaths.test.ts
 create mode 100644 packages/github-publisher/src/githubPaths.ts

diff --git a/README.md b/README.md
index 1ed4a19..71e9523 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,8 @@ The GitHub token never reaches the browser. It is read from `.env` on the server
 
 Details: [docs/github-publishing.md](docs/github-publishing.md) · [docs/media.md](docs/media.md)
 
+v0.1 uses the GitHub Contents API — suitable for typical blogs; very large content folders are a known MVP limitation.
+
 ## Quickstart
 
 Requirements: Node.js 22+, pnpm 11+
diff --git a/apps/studio/server/media.ts b/apps/studio/server/media.ts
index 7f129e3..887bf28 100644
--- a/apps/studio/server/media.ts
+++ b/apps/studio/server/media.ts
@@ -257,12 +257,16 @@ export async function uploadMedia(
     path: repoPath,
     contentBase64: parsed.buffer.toString("base64"),
     message: `Upload media: ${repoFilename}`,
+    purpose: "media",
   });
 
   if (!result.ok) {
     return {
       status: 502,
-      body: { ok: false, error: result.error },
+      body: {
+        ok: false,
+        error: result.error || "Media upload to GitHub failed.",
+      },
     };
   }
 
diff --git a/apps/studio/server/posts.ts b/apps/studio/server/posts.ts
index 21c4fbc..e0b5114 100644
--- a/apps/studio/server/posts.ts
+++ b/apps/studio/server/posts.ts
@@ -175,11 +175,11 @@ export async function listPosts(
 ): Promise<{ status: number; body: PostsListResponse }> {
   const publisher = createPublisher(env);
   const contentDir = normalizeContentDir(env.contentDir);
-  const listed = await publisher.listFiles({ path: contentDir });
+  const listed = await publisher.listFiles({ path: contentDir, contentDir });
 
   if (!listed.ok) {
     return {
-      status: 502,
+      status: listed.status === 404 ? 404 : 502,
       body: { ok: false, error: listed.error },
     };
   }
@@ -246,8 +246,9 @@ export async function loadPost(
   const loaded = await publisher.readFile({ path: safe.path });
 
   if (!loaded.ok) {
+    const status = loaded.status === 404 ? 404 : 502;
     return {
-      status: loaded.status === 404 ? 404 : 502,
+      status,
       body: { ok: false, error: loaded.error },
     };
   }
diff --git a/apps/studio/server/publish.ts b/apps/studio/server/publish.ts
index 8756682..423a9e2 100644
--- a/apps/studio/server/publish.ts
+++ b/apps/studio/server/publish.ts
@@ -100,12 +100,13 @@ export async function publishArticle(
     path,
     content,
     message: `Publish: ${article.slug}`,
+    purpose: "post",
   });
 
   if (!result.ok) {
     const errorBody: PublishErrorResponse = {
       ok: false,
-      error: result.error,
+      error: result.error || "Publish to GitHub failed.",
     };
 
     if (result.status !== undefined) {
diff --git a/apps/studio/src/App.tsx b/apps/studio/src/App.tsx
index 1b3d03c..09e24bf 100644
--- a/apps/studio/src/App.tsx
+++ b/apps/studio/src/App.tsx
@@ -256,7 +256,9 @@ function App() {
       }
 
       const action = result.created ? "Created" : "Updated";
-      setPublishSuccess(`${action} ${result.path} (${result.commitSha.slice(0, 7)})`);
+      setPublishSuccess(
+        `${action} output file ${result.path} (commit ${result.commitSha.slice(0, 7)}).`,
+      );
       setEditingPath(result.path);
       await refreshPosts();
     } catch {
@@ -269,7 +271,9 @@ function App() {
   if (!authChecked) {
     return (
       <div className="login-screen">
-        <p className="login-screen__loading">Checking session...</p>
+        <p className="login-screen__loading" role="status">
+          Checking session…
+        </p>
       </div>
     );
   }
@@ -292,14 +296,16 @@ function App() {
         {view === "overview" && (
           <div className="studio__stack">
             {loadPostError && (
-              <p className="article-pipeline__error article-pipeline__error--banner">
-                {loadPostError}
-              </p>
+              <div className="notice notice--error" role="alert">
+                <p className="notice__title">Could not open post</p>
+                <p className="notice__body">{loadPostError}</p>
+              </div>
             )}
             <ArticlePipeline
               posts={posts}
               loading={postsLoading}
               error={postsError}
+              githubReady={githubReady}
               onRefresh={() => {
                 void refreshPosts();
               }}
@@ -320,10 +326,13 @@ function App() {
           <div className="studio__editor-layout">
             <div className="studio__editor-column">
               {editingPath && (
-                <p className="editor-notice">
-                  Editing <code>{editingPath}</code>. Publishing will update this
-                  file in GitHub.
-                </p>
+                <div className="notice notice--info editor-notice" role="status">
+                  <p className="notice__title">Editing an existing post</p>
+                  <p className="notice__body">
+                    Changes will update output file{" "}
+                    <code>{editingPath}</code> on GitHub.
+                  </p>
+                </div>
               )}
               <EditorWorkspace body={form.body} onBodyChange={handleBodyChange} />
               {fieldErrors.body && (
@@ -349,7 +358,7 @@ function App() {
             <FrontmatterInspector
               values={form}
               categories={studioConfig.categories}
-              mediaDir={studioConfig.mediaDir}
+              githubReady={githubReady}
               fieldErrors={fieldErrors}
               slugAuto={slugAuto}
               onChange={handleFieldChange}
@@ -365,17 +374,17 @@ function App() {
           <div className="studio__stack">
             <section className="panel settings-panel">
               <div className="panel__header">
-                <h2 className="panel__title">Publishing configuration</h2>
+                <h2 className="panel__title">Settings</h2>
                 <p className="panel__meta">
-                  Paths and categories from sourcedraft.config.json. GitHub
-                  target from .env.
+                  Project paths from config · GitHub target from .env
                 </p>
               </div>
 
               <p className="settings-panel__note">
-                Publishing requires a GitHub token with write access to the
-                target repository. The token is read only by the server when you
-                publish.
+                These values are read-only here. Edit{" "}
+                <code>sourcedraft.config.json</code> for folders and categories, and{" "}
+                <code>.env</code> for GitHub credentials. The token never reaches
+                the browser.
               </p>
 
               <div className="settings-panel__grid">
diff --git a/apps/studio/src/components/AdapterStatus.tsx b/apps/studio/src/components/AdapterStatus.tsx
index 7625acf..0ac8fb4 100644
--- a/apps/studio/src/components/AdapterStatus.tsx
+++ b/apps/studio/src/components/AdapterStatus.tsx
@@ -21,29 +21,30 @@ export function AdapterStatus({
     githubOwner.trim().length > 0 && githubRepo.trim().length > 0;
 
   const rows: StatusRow[] = [
-    { label: "Adapter", value: adapter, state: "ok" },
-    { label: "Output path", value: contentDir, state: "ok" },
+    { label: "Output format", value: adapter, state: "ok" },
+    { label: "Content folder", value: contentDir, state: "ok" },
     {
-      label: "GitHub target",
+      label: "GitHub repository",
       value: githubReady ? `${githubOwner}/${githubRepo}` : "Not configured",
       state: githubReady ? "idle" : "off",
     },
     {
       label: "GitHub token",
-      value: "Checked server-side on publish",
-      state: "idle",
+      value: "Used on the server when you publish",
+      state: githubReady ? "idle" : "off",
     },
-    { label: "Auth", value: "Local password session", state: "ok" },
   ];
 
   return (
-    <section className="panel adapter-status">
+    <section className="panel adapter-status" aria-labelledby="setup-panel-title">
       <div className="panel__header">
-        <h2 className="panel__title">Publishing setup</h2>
+        <h2 className="panel__title" id="setup-panel-title">
+          Publishing setup
+        </h2>
         <p className="panel__meta">
           {githubReady
-            ? "GitHub repo configured in .env"
-            : "Set GITHUB_OWNER and GITHUB_REPO in .env to publish"}
+            ? "Connected to your GitHub repository"
+            : "Finish GitHub setup in .env to publish"}
         </p>
       </div>
 
@@ -56,7 +57,7 @@ export function AdapterStatus({
                 className={`adapter-status__dot adapter-status__dot--${row.state}`}
                 aria-hidden="true"
               />
-              {row.value}
+              <span>{row.value}</span>
             </dd>
           </div>
         ))}
diff --git a/apps/studio/src/components/ArticlePipeline.tsx b/apps/studio/src/components/ArticlePipeline.tsx
index 4d4783c..4cec052 100644
--- a/apps/studio/src/components/ArticlePipeline.tsx
+++ b/apps/studio/src/components/ArticlePipeline.tsx
@@ -4,6 +4,7 @@ type ArticlePipelineProps = {
   posts: PostSummary[];
   loading: boolean;
   error: string | null;
+  githubReady: boolean;
   onRefresh: () => void;
   onEdit: (path: string) => void;
 };
@@ -12,16 +13,19 @@ export function ArticlePipeline({
   posts,
   loading,
   error,
+  githubReady,
   onRefresh,
   onEdit,
 }: ArticlePipelineProps) {
   return (
-    <section className="panel article-pipeline">
+    <section className="panel article-pipeline" aria-labelledby="posts-panel-title">
       <div className="panel__header">
-        <h2 className="panel__title">Articles</h2>
-        <p className="panel__meta">
+        <h2 className="panel__title" id="posts-panel-title">
+          Your posts
+        </h2>
+        <p className="panel__meta" aria-live="polite">
           {loading
-            ? "Loading from GitHub..."
+            ? "Loading posts from GitHub…"
             : `${posts.length} post${posts.length === 1 ? "" : "s"} in your content folder`}
         </p>
         <button
@@ -30,34 +34,66 @@ export function ArticlePipeline({
           disabled={loading}
           onClick={onRefresh}
         >
-          Refresh
+          Refresh list
         </button>
       </div>
 
+      {loading && (
+        <div className="empty-state" role="status">
+          <p className="empty-state__title">Loading posts…</p>
+          <p className="empty-state__body">
+            Fetching posts from your GitHub content folder. This may take a moment
+            for larger sites.
+          </p>
+        </div>
+      )}
+
+      {!githubReady && !loading && (
+        <div className="notice notice--warning" role="status">
+          <p className="notice__title">GitHub is not configured yet</p>
+          <p className="notice__body">
+            Set <code>GITHUB_OWNER</code> and <code>GITHUB_REPO</code> in{" "}
+            <code>.env</code>, then open <strong>Settings</strong> to confirm the
+            target repository. You can still write drafts locally.
+          </p>
+        </div>
+      )}
+
       {error && (
-        <p className="article-pipeline__error">{error}</p>
+        <div className="notice notice--error" role="alert">
+          <p className="notice__title">Could not load posts</p>
+          <p className="notice__body">{error}</p>
+          <p className="notice__hint">
+            Check your GitHub token, repository settings, and{" "}
+            <code>contentDir</code> in Settings. Use Refresh list after fixing
+            configuration.
+          </p>
+        </div>
       )}
 
       {!loading && !error && posts.length === 0 && (
         <div className="empty-state">
-          <p className="empty-state__title">No posts yet</p>
+          <p className="empty-state__title">No posts found</p>
           <p className="empty-state__body">
-            Use <strong>New Article</strong> to write your first post. After you
-            publish, it will show up here so you can edit it later.
+            {githubReady
+              ? "Nothing matched your content folder yet. Open Write to draft a post, then publish to GitHub. Published posts appear here for editing."
+              : "Configure GitHub in Settings, then open Write to create your first post."}
           </p>
         </div>
       )}
 
-      {posts.length > 0 && (
+      {!loading && posts.length > 0 && (
         <div className="article-pipeline__table-wrap">
           <table className="article-pipeline__table">
             <thead>
               <tr>
-                <th>Title</th>
-                <th>Date</th>
-                <th>Category</th>
-                <th>Status</th>
-                <th aria-label="Actions" />
+                <th scope="col">Title</th>
+                <th scope="col">Date</th>
+                <th scope="col">Category</th>
+                <th scope="col">Status</th>
+                <th scope="col" className="article-pipeline__actions">
+                  <span className="visually-hidden">Actions</span>
+                </th>
               </tr>
             </thead>
             <tbody>
@@ -65,7 +101,7 @@ export function ArticlePipeline({
                 <tr key={post.path}>
                   <td>
                     <span className="article-pipeline__title">{post.title}</span>
-                    <code className="article-pipeline__path">{post.path}</code>
+                    <span className="article-pipeline__path">{post.path}</span>
                   </td>
                   <td className="article-pipeline__mono">{post.pubDate}</td>
                   <td>{post.category}</td>
@@ -77,7 +113,7 @@ export function ArticlePipeline({
                           : "article-pipeline__badge article-pipeline__badge--ready"
                       }
                     >
-                      {post.draft ? "Draft" : "Published"}
+                      {post.draft ? "Draft" : "Live"}
                     </span>
                   </td>
                   <td className="article-pipeline__actions">
diff --git a/apps/studio/src/components/AstroMdxPreview.tsx b/apps/studio/src/components/AstroMdxPreview.tsx
index 5aa94b2..2643ce9 100644
--- a/apps/studio/src/components/AstroMdxPreview.tsx
+++ b/apps/studio/src/components/AstroMdxPreview.tsx
@@ -12,7 +12,7 @@ type AstroMdxPreviewProps = {
 };
 
 function previewLabel(adapter: string): string {
-  return adapter === "markdown" ? "Markdown output" : "Astro MDX output";
+  return adapter === "markdown" ? "Markdown preview" : "MDX preview";
 }
 
 export function AstroMdxPreview({
@@ -40,20 +40,22 @@ export function AstroMdxPreview({
       : null;
 
   return (
-    <section className="panel mdx-output">
+    <section className="panel mdx-output" aria-labelledby="preview-panel-title">
       <div className="panel__header">
-        <h2 className="panel__title">{previewLabel(adapter)}</h2>
+        <h2 className="panel__title" id="preview-panel-title">
+          {previewLabel(adapter)}
+        </h2>
         <p className="panel__meta">
           {valid
-            ? "Preview of the file that will be committed"
-            : "Fix validation issues to preview output"}
+            ? "Review the file that will be saved to GitHub"
+            : "Complete post details and body to preview"}
         </p>
       </div>
 
       {valid && resolvedOutputPath && fileOutput ? (
         <div className="mdx-output__content">
           <div className="mdx-output__path">
-            <span className="mdx-output__path-label">Output path</span>
+            <span className="mdx-output__path-label">Output file</span>
             <code>{resolvedOutputPath}</code>
           </div>
           <pre className="mdx-output__code">
@@ -61,14 +63,27 @@ export function AstroMdxPreview({
           </pre>
         </div>
       ) : (
-        <ul className="validation-panel__issues mdx-output__issues">
-          {issues.map((issue) => (
-            <li key={`${issue.field}-${issue.message}`}>
-              <span className="validation-panel__field">{issue.field}</span>
-              {issue.message}
-            </li>
-          ))}
-        </ul>
+        <div className="validation-panel">
+          {issues.length === 0 ? (
+            <p className="validation-panel__intro">
+              Add a title, description, dates, category, and body to continue.
+            </p>
+          ) : (
+            <>
+              <p className="validation-panel__intro" role="status">
+                Fix these items before publishing:
+              </p>
+              <ul className="validation-panel__issues mdx-output__issues">
+                {issues.map((issue) => (
+                  <li key={`${issue.field}-${issue.message}`}>
+                    <span className="validation-panel__field">{issue.field}</span>
+                    {issue.message}
+                  </li>
+                ))}
+              </ul>
+            </>
+          )}
+        </div>
       )}
     </section>
   );
diff --git a/apps/studio/src/components/CommandBar.tsx b/apps/studio/src/components/CommandBar.tsx
index 46e3a12..402cad6 100644
--- a/apps/studio/src/components/CommandBar.tsx
+++ b/apps/studio/src/components/CommandBar.tsx
@@ -7,8 +7,8 @@ type CommandBarProps = {
 };
 
 const NAV_ITEMS: { id: View; label: string }[] = [
-  { id: "overview", label: "Overview" },
-  { id: "new-article", label: "New Article" },
+  { id: "overview", label: "Posts" },
+  { id: "new-article", label: "Write" },
   { id: "settings", label: "Settings" },
 ];
 
@@ -23,7 +23,7 @@ export function CommandBar({
         <span className="command-bar__mark">SD</span>
         <div>
           <p className="command-bar__title">SourceDraft Studio</p>
-          <p className="command-bar__subtitle">Markdown / MDX writing workspace</p>
+          <p className="command-bar__subtitle">Write, preview, and publish to GitHub</p>
         </div>
       </div>
 
diff --git a/apps/studio/src/components/EditorWorkspace.tsx b/apps/studio/src/components/EditorWorkspace.tsx
index bab1f08..9da1647 100644
--- a/apps/studio/src/components/EditorWorkspace.tsx
+++ b/apps/studio/src/components/EditorWorkspace.tsx
@@ -7,8 +7,8 @@ export function EditorWorkspace({ body, onBodyChange }: EditorWorkspaceProps) {
   return (
     <section className="panel editor-workspace">
       <div className="panel__header">
-        <h2 className="panel__title">Body</h2>
-        <p className="panel__meta">MDX / Markdown</p>
+        <h2 className="panel__title">Write</h2>
+        <p className="panel__meta">Markdown or MDX body</p>
       </div>
 
       <textarea
diff --git a/apps/studio/src/components/FrontmatterInspector.tsx b/apps/studio/src/components/FrontmatterInspector.tsx
index e6f143a..5cf3884 100644
--- a/apps/studio/src/components/FrontmatterInspector.tsx
+++ b/apps/studio/src/components/FrontmatterInspector.tsx
@@ -4,7 +4,7 @@ import { MediaDropzone } from "./MediaDropzone";
 type FrontmatterInspectorProps = {
   values: ArticleFormState;
   categories: string[];
-  mediaDir: string;
+  githubReady: boolean;
   fieldErrors: Record<string, string>;
   slugAuto: boolean;
   onChange: (field: keyof ArticleFormState, value: string | boolean) => void;
@@ -17,7 +17,7 @@ type FrontmatterInspectorProps = {
 export function FrontmatterInspector({
   values,
   categories,
-  mediaDir,
+  githubReady,
   fieldErrors,
   slugAuto,
   onChange,
@@ -35,8 +35,8 @@ export function FrontmatterInspector({
   return (
     <aside className="panel frontmatter-inspector">
       <div className="panel__header">
-        <h2 className="panel__title">Frontmatter</h2>
-        <p className="panel__meta">Title, dates, category, tags, draft</p>
+        <h2 className="panel__title">Post details</h2>
+        <p className="panel__meta">Title, dates, category, and cover image</p>
       </div>
 
       <div className="frontmatter-inspector__grid">
@@ -162,19 +162,25 @@ export function FrontmatterInspector({
         </label>
 
         <label className="field field--full">
-          <span className="field__label">Hero image</span>
+          <span className="field__label">Cover image</span>
           <input
             className={`${fieldClass("heroImage")} field__input--mono`}
             type="text"
             value={values.heroImage}
             onChange={(event) => onChange("heroImage", event.target.value)}
-            placeholder="/images/..."
+            placeholder="/images/your-cover.png"
+            aria-describedby="cover-image-hint"
           />
+          <span className="field__hint" id="cover-image-hint">
+            Public URL path used in frontmatter (heroImage)
+          </span>
           {fieldErrors.heroImage && (
-            <span className="field__error">{fieldErrors.heroImage}</span>
+            <span className="field__error" role="alert">
+              {fieldErrors.heroImage}
+            </span>
           )}
           <MediaDropzone
-            mediaDir={mediaDir}
+            githubReady={githubReady}
             onUseAsHero={onUseHeroImage}
             onInsertIntoBody={onInsertImage}
           />
diff --git a/apps/studio/src/components/LoginScreen.tsx b/apps/studio/src/components/LoginScreen.tsx
index 1119d63..d3df621 100644
--- a/apps/studio/src/components/LoginScreen.tsx
+++ b/apps/studio/src/components/LoginScreen.tsx
@@ -17,7 +17,7 @@ export function LoginScreen({ configured, onLogin }: LoginScreenProps) {
 
     const result = await onLogin(password);
     if (!result.ok) {
-      setError(result.error ?? "Login failed.");
+      setError(result.error ?? "Sign in failed. Check your password and try again.");
       setSubmitting(false);
       return;
     }
@@ -31,24 +31,27 @@ export function LoginScreen({ configured, onLogin }: LoginScreenProps) {
       <section className="panel login-screen__panel">
         <div className="panel__header">
           <h1 className="panel__title">SourceDraft Studio</h1>
-          <p className="panel__meta">Sign in to your local writing workspace</p>
+          <p className="panel__meta">Sign in to write and publish</p>
         </div>
 
         <form className="login-screen__form" onSubmit={handleSubmit}>
           <p className="login-screen__intro">
-            One shared admin password, checked on the server. There are no user
-            accounts in this MVP.
+            This workspace uses one shared password, checked on the server. It is
+            meant for local or private use.
           </p>
 
           {!configured && (
-            <p className="login-screen__notice">
-              Add <code>SOURCEDRAFT_ADMIN_PASSWORD</code> to <code>.env</code>{" "}
-              and restart the API server.
-            </p>
+            <div className="notice notice--warning" role="status">
+              <p className="notice__title">Password not configured</p>
+              <p className="notice__body">
+                Add <code>SOURCEDRAFT_ADMIN_PASSWORD</code> to <code>.env</code>{" "}
+                and restart the API server.
+              </p>
+            </div>
           )}
 
           <label className="field field--full">
-            <span className="field__label">Admin password</span>
+            <span className="field__label">Password</span>
             <input
               className="field__input field__input--mono"
               type="password"
@@ -59,14 +62,18 @@ export function LoginScreen({ configured, onLogin }: LoginScreenProps) {
             />
           </label>
 
-          {error && <p className="login-screen__error">{error}</p>}
+          {error && (
+            <p className="login-screen__error" role="alert">
+              {error}
+            </p>
+          )}
 
           <button
             type="submit"
             className="button button--primary login-screen__submit"
             disabled={!configured || submitting || password.length === 0}
           >
-            {submitting ? "Signing in..." : "Sign in"}
+            {submitting ? "Signing in…" : "Sign in"}
           </button>
         </form>
       </section>
diff --git a/apps/studio/src/components/MediaDropzone.tsx b/apps/studio/src/components/MediaDropzone.tsx
index 27f955f..e5d0267 100644
--- a/apps/studio/src/components/MediaDropzone.tsx
+++ b/apps/studio/src/components/MediaDropzone.tsx
@@ -1,4 +1,4 @@
-import { useRef, useState, type DragEvent } from "react";
+import { useRef, useState, type DragEvent, type KeyboardEvent } from "react";
 import { uploadMedia } from "../lib/media";
 
 const ACCEPTED_TYPES = new Set([
@@ -9,7 +9,7 @@ const ACCEPTED_TYPES = new Set([
 ]);
 
 type MediaDropzoneProps = {
-  mediaDir: string;
+  githubReady: boolean;
   onUseAsHero: (publicPath: string) => void;
   onInsertIntoBody: (publicPath: string) => void;
 };
@@ -21,7 +21,7 @@ type UploadState =
   | { status: "error"; message: string };
 
 export function MediaDropzone({
-  mediaDir,
+  githubReady,
   onUseAsHero,
   onInsertIntoBody,
 }: MediaDropzoneProps) {
@@ -29,15 +29,25 @@ export function MediaDropzone({
   const [dragActive, setDragActive] = useState(false);
   const [upload, setUpload] = useState<UploadState>({ status: "idle" });
 
+  const uploadDisabled = !githubReady || upload.status === "uploading";
+
   async function handleFile(file: File | null | undefined) {
-    if (!file) {
+    if (!file || uploadDisabled) {
       return;
     }
 
     if (!ACCEPTED_TYPES.has(file.type)) {
       setUpload({
         status: "error",
-        message: "Choose a PNG, JPEG, GIF, or WebP image.",
+        message: "Use a PNG, JPEG, GIF, or WebP image.",
+      });
+      return;
+    }
+
+    if (file.size > 5 * 1024 * 1024) {
+      setUpload({
+        status: "error",
+        message: "Image must be 5 MB or smaller.",
       });
       return;
     }
@@ -59,7 +69,9 @@ export function MediaDropzone({
 
   function handleDragOver(event: DragEvent<HTMLDivElement>) {
     event.preventDefault();
-    setDragActive(true);
+    if (!uploadDisabled) {
+      setDragActive(true);
+    }
   }
 
   function handleDragLeave(event: DragEvent<HTMLDivElement>) {
@@ -73,6 +85,17 @@ export function MediaDropzone({
     void handleFile(event.dataTransfer.files.item(0));
   }
 
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    if (uploadDisabled) {
+      return;
+    }
+
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      inputRef.current?.click();
+    }
+  }
+
   function resetUpload() {
     setUpload({ status: "idle" });
     if (inputRef.current) {
@@ -88,29 +111,48 @@ export function MediaDropzone({
             ? "media-dropzone__target media-dropzone__target--active"
             : "media-dropzone__target"
         }
+        role="group"
+        aria-label="Image upload"
+        tabIndex={uploadDisabled ? -1 : 0}
         onDragOver={handleDragOver}
         onDragLeave={handleDragLeave}
         onDrop={handleDrop}
+        onKeyDown={handleKeyDown}
+        aria-disabled={uploadDisabled}
       >
-        <p className="media-dropzone__label">Drop an image here</p>
+        <p className="media-dropzone__label">
+          Drag an image here, or choose a file
+        </p>
         <p className="media-dropzone__hint">
-          PNG, JPEG, GIF, or WebP up to 5 MB. Uploads go to{" "}
-          <code>{mediaDir}</code> through the server — your GitHub token never
-          leaves the API.
+          PNG, JPEG, GIF, or WebP · max 5 MB. Uploads are committed to your site
+          repo through the server.
         </p>
+        {!githubReady && (
+          <p className="media-dropzone__hint media-dropzone__hint--warning" role="status">
+            Configure GitHub in Settings before uploading images.
+          </p>
+        )}
         <button
           type="button"
           className="button button--compact"
-          disabled={upload.status === "uploading"}
+          disabled={uploadDisabled}
+          aria-describedby={uploadDisabled ? "upload-disabled-reason" : undefined}
           onClick={() => inputRef.current?.click()}
         >
-          {upload.status === "uploading" ? "Uploading..." : "Choose image"}
+          {upload.status === "uploading" ? "Uploading…" : "Choose image"}
         </button>
+        {uploadDisabled && githubReady === false && (
+          <span id="upload-disabled-reason" className="visually-hidden">
+            GitHub owner and repository are not configured
+          </span>
+        )}
         <input
           ref={inputRef}
+          id="media-upload-input"
           className="media-dropzone__input"
           type="file"
           accept="image/png,image/jpeg,image/gif,image/webp"
+          disabled={uploadDisabled}
           onChange={(event) => {
             void handleFile(event.target.files?.item(0));
           }}
@@ -118,7 +160,10 @@ export function MediaDropzone({
       </div>
 
       {upload.status === "error" && (
-        <p className="media-dropzone__message media-dropzone__message--error">
+        <p
+          className="media-dropzone__message media-dropzone__message--error"
+          role="alert"
+        >
           {upload.message}
         </p>
       )}
@@ -126,17 +171,21 @@ export function MediaDropzone({
       {upload.status === "success" && (
         <div className="media-dropzone__result">
           <p className="media-dropzone__message media-dropzone__message--success">
-            Uploaded <code>{upload.publicPath}</code>
+            Image ready at{" "}
+            <code className="media-dropzone__path">{upload.publicPath}</code>
+          </p>
+          <p className="media-dropzone__hint">
+            Use this path in your cover image field or body Markdown.
           </p>
           <div className="media-dropzone__actions">
             <button
               type="button"
-              className="button button--compact"
+              className="button button--compact button--primary"
               onClick={() => {
                 onUseAsHero(upload.publicPath);
               }}
             >
-              Use as hero image
+              Use as cover image
             </button>
             <button
               type="button"
diff --git a/apps/studio/src/components/PublishGate.tsx b/apps/studio/src/components/PublishGate.tsx
index f081ded..7640053 100644
--- a/apps/studio/src/components/PublishGate.tsx
+++ b/apps/studio/src/components/PublishGate.tsx
@@ -7,6 +7,26 @@ type PublishGateProps = {
   onPublish: () => void;
 };
 
+function disabledReason(
+  ready: boolean,
+  githubReady: boolean,
+  publishing: boolean,
+): string | null {
+  if (publishing) {
+    return null;
+  }
+
+  if (!githubReady) {
+    return "Set GITHUB_OWNER, GITHUB_REPO, and GITHUB_TOKEN in .env, then check Settings.";
+  }
+
+  if (!ready) {
+    return "Complete post details and fix validation issues first.";
+  }
+
+  return null;
+}
+
 export function PublishGate({
   ready,
   publishing,
@@ -16,49 +36,59 @@ export function PublishGate({
   onPublish,
 }: PublishGateProps) {
   const canPublish = ready && !publishing && githubReady;
+  const reason = disabledReason(ready, githubReady, publishing);
 
   return (
-    <section className="panel publish-gate">
+    <section className="panel publish-gate" aria-labelledby="publish-panel-title">
       <div className="panel__header">
-        <h2 className="panel__title">Publish</h2>
-        <p className="panel__meta">
+        <h2 className="panel__title" id="publish-panel-title">
+          Publish
+        </h2>
+        <p className="panel__meta" aria-live="polite">
           {publishing
-            ? "Committing MDX to GitHub..."
+            ? "Saving to GitHub…"
             : ready
-              ? "Article is valid"
-              : "Complete required fields first"}
+              ? "Ready to commit this post"
+              : "Validate your post before publishing"}
         </p>
       </div>
 
-      {!githubReady && (
-        <p className="publish-gate__hint">
-          Publishing needs <code>GITHUB_TOKEN</code>, <code>GITHUB_OWNER</code>,
-          and <code>GITHUB_REPO</code> in <code>.env</code>. The token stays on
-          the server and is never sent to the browser.
-        </p>
-      )}
-
       <div className="publish-gate__actions">
         <button
           type="button"
           className="button button--primary"
           disabled={!canPublish}
+          aria-describedby={reason ? "publish-disabled-reason" : undefined}
           onClick={onPublish}
         >
-          {publishing ? "Publishing..." : "Publish to GitHub"}
+          {publishing ? "Publishing…" : "Publish to GitHub"}
         </button>
       </div>
 
-      {publishError && (
-        <p className="publish-gate__message publish-gate__message--error">
-          {publishError}
+      {reason && (
+        <p className="publish-gate__hint" id="publish-disabled-reason">
+          {reason}
         </p>
       )}
 
+      {publishError && (
+        <div className="notice notice--error publish-gate__notice" role="alert">
+          <p className="notice__title">Publish failed</p>
+          <p className="notice__body">{publishError}</p>
+          <p className="notice__hint">
+            Check Settings for GitHub and path configuration, then try again.
+          </p>
+        </div>
+      )}
+
       {publishSuccess && (
-        <p className="publish-gate__message publish-gate__message--success">
-          {publishSuccess}
-        </p>
+        <div className="notice notice--success publish-gate__notice" role="status">
+          <p className="notice__title">Published</p>
+          <p className="notice__body">{publishSuccess}</p>
+          <p className="notice__hint">
+            Your site build or CI will pick up the new file from the repository.
+          </p>
+        </div>
       )}
     </section>
   );
diff --git a/apps/studio/src/index.css b/apps/studio/src/index.css
index 19ea5fb..8bb20f7 100644
--- a/apps/studio/src/index.css
+++ b/apps/studio/src/index.css
@@ -5,8 +5,8 @@
   --border: #2a2a2e;
   --border-strong: #3a3a40;
   --text: #d8d8dc;
-  --text-muted: #8a8a92;
-  --text-dim: #5c5c64;
+  --text-muted: #9a9aa3;
+  --text-dim: #72727c;
   --accent: #c8b68a;
   --accent-muted: #8f8265;
   --ok: #6f9f7a;
@@ -96,6 +96,10 @@ code {
   min-height: 0;
 }
 
+.studio__editor-column > .panel.publish-gate {
+  border-color: var(--border-strong);
+}
+
 .command-bar {
   display: grid;
   grid-template-columns: auto 1fr auto;
@@ -156,6 +160,13 @@ code {
   border-color: var(--border);
 }
 
+.command-bar__nav-item:focus-visible,
+.button:focus-visible,
+.media-dropzone__target:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
 .command-bar__nav-item--active {
   color: var(--text);
   border-color: var(--border-strong);
@@ -271,8 +282,9 @@ code {
 
 .article-pipeline__path {
   display: block;
+  font-family: var(--mono);
   font-size: 11px;
-  color: var(--text-dim);
+  color: var(--text-muted);
 }
 
 .article-pipeline__mono {
@@ -304,16 +316,6 @@ code {
 
 .editor-notice {
   margin: 0;
-  padding: 10px 12px;
-  border: 1px solid var(--border);
-  background: var(--bg-raised);
-  font-size: 12px;
-  color: var(--text-muted);
-  line-height: 1.5;
-}
-
-.editor-notice code {
-  color: var(--accent);
 }
 
 .media-dropzone {
@@ -330,6 +332,11 @@ code {
   padding: 12px;
   border: 1px dashed var(--border-strong);
   background: var(--bg);
+  border-radius: 2px;
+}
+
+.media-dropzone__target[aria-disabled="true"] {
+  opacity: 0.65;
 }
 
 .media-dropzone__target--active {
@@ -350,6 +357,14 @@ code {
   line-height: 1.5;
 }
 
+.media-dropzone__hint--warning {
+  color: var(--idle);
+}
+
+.media-dropzone__path {
+  color: var(--accent);
+}
+
 .media-dropzone__input {
   display: none;
 }
@@ -555,18 +570,21 @@ select.field__input:focus {
   border-top: none;
 }
 
-.validation-panel__ok {
-  margin: 0;
+.validation-panel {
   padding: 12px;
+}
+
+.validation-panel__intro {
+  margin: 0 0 10px;
   font-size: 12px;
-  color: var(--ok);
-  font-family: var(--mono);
+  color: var(--text-muted);
+  line-height: 1.55;
 }
 
 .validation-panel__issues {
   list-style: none;
   margin: 0;
-  padding: 12px;
+  padding: 0;
   display: flex;
   flex-direction: column;
   gap: 6px;
@@ -652,12 +670,16 @@ select.field__input {
 
 .publish-gate__hint {
   margin: 0;
-  padding: 12px 12px 0;
+  padding: 0 12px 12px;
   font-size: 12px;
   color: var(--text-muted);
   line-height: 1.5;
 }
 
+.publish-gate__notice {
+  margin: 0 12px 12px;
+}
+
 .publish-gate__actions {
   display: flex;
   gap: 8px;
@@ -691,19 +713,69 @@ select.field__input {
   border-bottom: 1px solid var(--border);
 }
 
-.publish-gate__message {
+.notice {
+  padding: 12px;
+  border: 1px solid var(--border);
+  background: var(--bg-raised);
+  line-height: 1.55;
+}
+
+.notice__title {
+  margin: 0 0 6px;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.notice__body {
   margin: 0;
-  padding: 0 12px 12px;
   font-size: 12px;
-  font-family: var(--mono);
+  color: var(--text-muted);
 }
 
-.publish-gate__message--error {
-  color: var(--danger);
+.notice__hint {
+  margin: 8px 0 0;
+  font-size: 11px;
+  color: var(--text-dim);
 }
 
-.publish-gate__message--success {
-  color: var(--ok);
+.notice--error {
+  border-color: #5a3f3f;
+  background: #161012;
+}
+
+.notice--error .notice__title {
+  color: #d4a0a0;
+}
+
+.notice--success {
+  border-color: #3f5a45;
+  background: #101612;
+}
+
+.notice--success .notice__title {
+  color: #9fd4a8;
+}
+
+.notice--warning {
+  border-color: #5a523f;
+  background: #14130f;
+}
+
+.notice--info {
+  border-color: var(--border-strong);
+}
+
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
 }
 
 .button {
@@ -720,8 +792,9 @@ select.field__input {
 }
 
 .button:disabled {
-  opacity: 0.45;
+  opacity: 0.55;
   cursor: not-allowed;
+  color: var(--text-dim);
 }
 
 .button--primary {
diff --git a/apps/studio/src/lib/media.ts b/apps/studio/src/lib/media.ts
index 8e33d5f..9655c82 100644
--- a/apps/studio/src/lib/media.ts
+++ b/apps/studio/src/lib/media.ts
@@ -28,7 +28,11 @@ export async function uploadMedia(file: File): Promise<MediaUploadResponse> {
 
     if (!response.ok || !data.ok) {
       return data.ok
-        ? { ok: false, error: "Image upload failed." }
+        ? {
+            ok: false,
+            error:
+              "Media upload failed. Check token, owner/repo, and mediaDir.",
+          }
         : data;
     }
 
diff --git a/apps/studio/src/lib/posts.ts b/apps/studio/src/lib/posts.ts
index 66daaab..cca65ea 100644
--- a/apps/studio/src/lib/posts.ts
+++ b/apps/studio/src/lib/posts.ts
@@ -46,7 +46,11 @@ export async function fetchPosts(): Promise<FetchPostsResponse> {
 
     if (!response.ok || !data.ok) {
       return data.ok
-        ? { ok: false, error: "Could not load posts." }
+        ? {
+            ok: false,
+            error:
+              "Could not load posts. Check GitHub token, owner/repo, and contentDir.",
+          }
         : data;
     }
 
@@ -66,7 +70,10 @@ export async function fetchPost(path: string): Promise<FetchPostResponse> {
 
     if (!response.ok || !data.ok) {
       return data.ok
-        ? { ok: false, error: "Could not load post." }
+        ? {
+            ok: false,
+            error: "Could not open this post. It may have been moved or deleted.",
+          }
         : data;
     }
 
diff --git a/apps/studio/src/lib/publish.ts b/apps/studio/src/lib/publish.ts
index 1cd49ec..b35c4c2 100644
--- a/apps/studio/src/lib/publish.ts
+++ b/apps/studio/src/lib/publish.ts
@@ -40,7 +40,11 @@ export async function publishArticle(
 
   if (!response.ok || !data.ok) {
     return data.ok
-      ? { ok: false, error: "Publish failed." }
+      ? {
+          ok: false,
+          error:
+            "Publish to GitHub failed. Check token, owner/repo, and contentDir.",
+        }
       : data;
   }
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 8bbe688..78d9fb0 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -82,6 +82,8 @@ SourceDraft searches for `sourcedraft.config.json` in the working directory, up
 
 Missing file → built-in defaults matching the example above.
 
+Wrong `contentDir` or `mediaDir` values produce clear GitHub errors in Studio when listing posts, opening a post, publishing, or uploading media. See [github-publishing.md](github-publishing.md#common-failures).
+
 ## Environment variables
 
 ```env
diff --git a/docs/github-publishing.md b/docs/github-publishing.md
index 88462a7..bee2998 100644
--- a/docs/github-publishing.md
+++ b/docs/github-publishing.md
@@ -10,7 +10,7 @@ In `.env` (never committed):
 
 | Variable | Role |
 |----------|------|
-| `GITHUB_TOKEN` | Authenticates with GitHub (write access to repo contents) |
+| `GITHUB_TOKEN` | Authenticates with GitHub (read/write access to repo contents) |
 | `GITHUB_OWNER` | User or organization that owns the repo |
 | `GITHUB_REPO` | Repository name for your **site**, not necessarily this SourceDraft repo |
 | `GITHUB_BRANCH` | Optional; defaults to `defaultBranch` in `sourcedraft.config.json` |
@@ -20,10 +20,34 @@ In `sourcedraft.config.json`:
 | Field | Role |
 |-------|------|
 | `contentDir` | Folder inside the repo where post files are written |
+| `mediaDir` | Folder where image uploads are committed |
 | `adapter` | Output format (`astro-mdx` or `markdown`) |
 
 The same token is used for media uploads to `mediaDir`. See [media.md](media.md).
 
+## GitHub Contents API (v0.1)
+
+SourceDraft v0.1 uses the [GitHub Contents API](https://docs.github.com/en/rest/repos/contents) for:
+
+- creating and updating post files
+- listing and reading existing posts under `contentDir`
+- uploading media files under `mediaDir`
+
+This is intentional MVP scope: simple Git-backed publishing without a database or content indexer.
+
+**Works well for:** typical blogs and small/medium content folders.
+
+**Known limits:**
+
+| Limit | Effect |
+|-------|--------|
+| ~1 MB per file (inline content) | Very large post or media files cannot be read or published inline |
+| 1000 entries per directory listing | A single folder with more than 1000 items cannot be fully listed |
+| No intermediate folder creation | Parent folders for `mediaDir` must already exist in the repo |
+| Recursive listing | Deep trees require multiple API calls; large sites are slower |
+
+**Future improvement:** Git Trees API or indexed content listing for very large repositories. v0.1 prioritizes straightforward Git publishing over large-scale indexing.
+
 ## Step by step
 
 1. **Studio** sends article JSON to `POST /api/publish` (cookie session required). When editing an existing post, it includes `sourcePath` so the same repo file is updated.
@@ -41,6 +65,8 @@ Your Astro (or other) build runs separately — on push, in CI, or locally.
 
 `GET /api/posts` lists `.md` and `.mdx` files under `contentDir`. `GET /api/posts?path=...` loads one post for editing. Paths are validated server-side so requests cannot escape `contentDir`.
 
+Existing post listing and editing works for normal GitHub content folders. If `contentDir` is wrong or missing, Studio shows a clear error pointing at config and the repo.
+
 ## What never touches the browser
 
 - `GITHUB_TOKEN`
@@ -50,14 +76,22 @@ Studio only holds a session cookie after login.
 
 ## Common failures
 
-| Message / symptom | Check |
-|-------------------|--------|
+| Symptom | Likely cause |
+|---------|----------------|
 | Authentication required | Sign in to Studio |
 | `GITHUB_TOKEN is not configured` | `.env` on server, restart API |
-| 401 / 403 from GitHub | Token scope or repo access |
-| Wrong path | `contentDir` in config vs your site layout |
+| GitHub rejected the token (401) | Missing, expired, or invalid `GITHUB_TOKEN` |
+| GitHub denied access (403) | Token lacks read/write contents permission on the repo/branch |
+| Could not find the posts folder | Wrong `contentDir` or folder missing on the branch |
+| Could not find the media folder | Wrong `mediaDir` or parent folders not created yet |
+| Repository not found | Wrong `GITHUB_OWNER` or `GITHUB_REPO` |
+| Post not found / could not open | File moved, renamed, or deleted on GitHub |
+| Directory listing limit reached | More than 1000 items in one folder — MVP Contents API limit |
+| File too large for Contents API | Post or image over ~1 MB inline limit |
 | Unsupported adapter | `adapter` must be `astro-mdx` or `markdown` |
 
+Studio surfaces these messages from the server where possible. Check `.env`, `sourcedraft.config.json`, and the target repo on GitHub.
+
 ## Token scope
 
 Use a personal access token that can read and write repository contents for the target repo. Fine-grained tokens should be limited to that repository.
diff --git a/docs/project-status.md b/docs/project-status.md
index b7eda97..97db7bb 100644
--- a/docs/project-status.md
+++ b/docs/project-status.md
@@ -5,10 +5,11 @@ Early open-source MVP — usable for single-editor writing and GitHub publishing
 ## What works
 
 - Studio editor with universal article fields
-- Post list and edit from GitHub (`contentDir`)
+- Post list and edit from GitHub (`contentDir`) for normal content folders
 - Validation (`@sourcedraft/core`)
 - Live preview for `astro-mdx` and `markdown` adapters
 - GitHub file create/update for posts and media (`@sourcedraft/github-publisher`)
+- Clearer GitHub API error messages for token, repo, path, and Contents API limits
 - Image upload from Studio (PNG, JPEG, GIF, WebP; 5 MB max)
 - `sourcedraft.config.json` + `.env` configuration
 - Server-side password auth for Studio and API
@@ -21,11 +22,18 @@ Early open-source MVP — usable for single-editor writing and GitHub publishing
 | Auth | One shared password; no OAuth or accounts |
 | Sessions | In-memory; lost when API restarts |
 | Hosting | You run Studio locally or on your own server |
-| Publishers | GitHub Contents API only |
+| Publishers | GitHub Contents API only (no Git Trees API yet) |
+| Large repos | Directory listings capped at 1000 entries per folder; inline files capped at ~1 MB |
 | Adapters | `astro-mdx` and `markdown` only |
 | Media | GitHub repo uploads only; no Cloudinary/S3/R2 |
 | Teams | No roles, review workflow, or multi-editor accounts |
 
+## Known MVP limitations (GitHub)
+
+- **Contents API scale:** fine for small and medium blogs; very large content trees may be slow or hit listing limits.
+- **No indexer:** post list walks the repo via the Contents API — no database or search index.
+- **Future improvement:** Git Trees API or indexed content listing for large sites.
+
 ## Intended use
 
 Open-source tool for developers and technical bloggers who accept these limits. Setup required — not a turnkey WordPress replacement or hosted writing product.
diff --git a/package.json b/package.json
index 4adfa9b..7e1bb10 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,7 @@
     "build": "pnpm -r build",
     "check": "pnpm -r check",
     "lint": "pnpm -r lint",
-    "test": "pnpm --filter @sourcedraft/core --filter @sourcedraft/adapter-astro-mdx --filter @sourcedraft/adapter-markdown test"
+    "test": "pnpm --filter @sourcedraft/core --filter @sourcedraft/adapter-astro-mdx --filter @sourcedraft/adapter-markdown --filter @sourcedraft/github-publisher test"
   },
   "devDependencies": {
     "tsx": "^4.20.3"
diff --git a/packages/github-publisher/package.json b/packages/github-publisher/package.json
index 5ccaab9..2256aea 100644
--- a/packages/github-publisher/package.json
+++ b/packages/github-publisher/package.json
@@ -15,10 +15,12 @@
   ],
   "scripts": {
     "build": "tsc",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "node --import tsx --test src/**/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^22.15.30",
+    "tsx": "^4.20.3",
     "typescript": "^5.8.3"
   }
 }
diff --git a/packages/github-publisher/src/githubErrors.test.ts b/packages/github-publisher/src/githubErrors.test.ts
new file mode 100644
index 0000000..dff4dc8
--- /dev/null
+++ b/packages/github-publisher/src/githubErrors.test.ts
@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  directoryListingLimitMessage,
+  formatGitHubApiError,
+  formatLocalGitHubError,
+  isDirectoryListingTruncated,
+  validateGitHubFileBody,
+} from "./githubErrors.js";
+
+describe("formatGitHubApiError", () => {
+  it("maps 401 to token guidance", () => {
+    const error = formatGitHubApiError(401, "Bad credentials", "publish");
+    assert.match(error, /GITHUB_TOKEN/);
+  });
+
+  it("maps 403 to scope guidance", () => {
+    const error = formatGitHubApiError(403, "Forbidden", "listPosts", {
+      owner: "acme",
+      repo: "blog",
+    });
+    assert.match(error, /acme\/blog/);
+    assert.match(error, /403/);
+  });
+
+  it("maps listPosts 404 to contentDir guidance", () => {
+    const error = formatGitHubApiError(404, "Not Found", "listPosts", {
+      owner: "acme",
+      repo: "blog",
+      contentDir: "src/content/blog",
+    });
+    assert.match(error, /src\/content\/blog/);
+    assert.match(error, /contentDir/);
+  });
+
+  it("maps uploadMedia 404 to mediaDir guidance", () => {
+    const error = formatGitHubApiError(404, "Not Found", "uploadMedia", {
+      mediaDir: "public/images",
+    });
+    assert.match(error, /public\/images/);
+    assert.match(error, /mediaDir/);
+  });
+});
+
+describe("validateGitHubFileBody", () => {
+  it("rejects directory paths", () => {
+    assert.equal(validateGitHubFileBody({ type: "dir", sha: "abc" }), "Path is not a file.");
+  });
+
+  it("rejects large files without inline content", () => {
+    const error = validateGitHubFileBody({
+      type: "file",
+      sha: "abc",
+      size: 2_000_000,
+    });
+    assert.notEqual(error, null);
+    assert.match(error as string, /too large/i);
+  });
+
+  it("accepts valid base64 file bodies", () => {
+    assert.equal(
+      validateGitHubFileBody({
+        type: "file",
+        sha: "abc",
+        content: "aGVsbG8=",
+        encoding: "base64",
+      }),
+      null,
+    );
+  });
+});
+
+describe("listing helpers", () => {
+  it("detects truncated directory listings", () => {
+    assert.equal(isDirectoryListingTruncated(999), false);
+    assert.equal(isDirectoryListingTruncated(1000), true);
+  });
+
+  it("documents the listing limit honestly", () => {
+    assert.match(directoryListingLimitMessage(), /Contents API/);
+    assert.match(directoryListingLimitMessage(), /Git Trees API/);
+  });
+});
+
+describe("formatLocalGitHubError", () => {
+  it("rewrites not-a-file errors with path context", () => {
+    const error = formatLocalGitHubError("Path is not a file.", "readPost", {
+      path: "src/content/blog",
+    });
+    assert.match(error, /folder/);
+  });
+});
diff --git a/packages/github-publisher/src/githubErrors.ts b/packages/github-publisher/src/githubErrors.ts
new file mode 100644
index 0000000..eb42b11
--- /dev/null
+++ b/packages/github-publisher/src/githubErrors.ts
@@ -0,0 +1,177 @@
+/** GitHub Contents API returns at most 1000 entries per directory listing. */
+export const GITHUB_DIRECTORY_LISTING_LIMIT = 1000;
+
+/** GitHub Contents API returns inline base64 content for files up to ~1 MB. */
+export const GITHUB_INLINE_FILE_SIZE_LIMIT = 1_000_000;
+
+export type GitHubOperation =
+  | "publish"
+  | "uploadMedia"
+  | "listPosts"
+  | "readPost"
+  | "checkFile";
+
+export type GitHubErrorContext = {
+  owner?: string;
+  repo?: string;
+  path?: string;
+  contentDir?: string;
+  mediaDir?: string;
+};
+
+type GitHubContentBody = {
+  type?: string;
+  content?: string;
+  encoding?: string;
+  sha?: string;
+  size?: number;
+};
+
+export function isDirectoryListingTruncated(entryCount: number): boolean {
+  return entryCount >= GITHUB_DIRECTORY_LISTING_LIMIT;
+}
+
+export function repoLabel(context: GitHubErrorContext): string {
+  if (context.owner && context.repo) {
+    return `${context.owner}/${context.repo}`;
+  }
+
+  return "the configured repository";
+}
+
+export function formatGitHubApiError(
+  status: number,
+  rawMessage: string,
+  operation: GitHubOperation,
+  context: GitHubErrorContext = {},
+): string {
+  const message = rawMessage.trim();
+  const target = repoLabel(context);
+
+  if (status === 401) {
+    return "GitHub rejected the token (401). Check GITHUB_TOKEN in .env — it may be missing, expired, or revoked.";
+  }
+
+  if (status === 403) {
+    if (/rate limit/i.test(message)) {
+      return "GitHub API rate limit reached. Wait a few minutes and try again.";
+    }
+
+    return `GitHub denied access to ${target} (403). The token needs read and write permission for repository contents on this repo and branch.`;
+  }
+
+  if (status === 404) {
+    if (/repository.*not found/i.test(message) || /not found.*repository/i.test(message)) {
+      return `Repository ${target} was not found. Check GITHUB_OWNER and GITHUB_REPO in .env.`;
+    }
+
+    if (operation === "listPosts") {
+      const folder = context.contentDir ?? context.path ?? "contentDir";
+      return `Could not find the posts folder "${folder}" in ${target}. Check contentDir in sourcedraft.config.json and that the folder exists on the configured branch.`;
+    }
+
+    if (operation === "uploadMedia") {
+      const folder = context.mediaDir ?? context.path ?? "mediaDir";
+      return `Could not find the media folder "${folder}" in ${target}. Check mediaDir in config. Parent folders must already exist in the repo.`;
+    }
+
+    if (operation === "readPost") {
+      const postPath = context.path ?? "the requested path";
+      return `Could not open post "${postPath}". It may have been moved, renamed, or deleted on GitHub.`;
+    }
+
+    if (operation === "publish" || operation === "checkFile") {
+      const filePath = context.path ?? "the target path";
+      return `GitHub could not find "${filePath}" in ${target} (404). Check contentDir and the post path.`;
+    }
+
+    return `GitHub could not find the requested path in ${target} (404).`;
+  }
+
+  if (status === 422) {
+    return `GitHub rejected the request (422). ${message || "Check the file path and branch."}`;
+  }
+
+  if (message.length > 0) {
+    return `GitHub API error (${status}): ${message}`;
+  }
+
+  return `GitHub API request failed (${status}).`;
+}
+
+export function formatLocalGitHubError(
+  message: string,
+  operation: GitHubOperation,
+  context: GitHubErrorContext = {},
+): string {
+  if (message === "Path is not a file.") {
+    const postPath = context.path ?? "That path";
+    return `${postPath} is a folder, not a post file.`;
+  }
+
+  if (message === "GitHub returned a file without a sha.") {
+    return "GitHub returned an unexpected file response (missing sha). Try again or check the repository state.";
+  }
+
+  if (message === "GitHub did not return the published file sha.") {
+    return "Publish appeared to succeed but GitHub did not return the new file sha. Check the repository on GitHub.";
+  }
+
+  if (message === "GitHub did not return the commit sha.") {
+    return "Publish appeared to succeed but GitHub did not return a commit sha. Check the repository on GitHub.";
+  }
+
+  if (message === "GitHub did not return base64 file content.") {
+    return "GitHub did not return readable file content. The file may be too large for the Contents API in v0.1.";
+  }
+
+  if (message.startsWith("GitHub directory listing limit reached")) {
+    return message;
+  }
+
+  return message;
+}
+
+export function validateGitHubFileBody(body: GitHubContentBody): string | null {
+  if (body.type !== "file") {
+    if (body.type === "dir") {
+      return "Path is not a file.";
+    }
+
+    return "Path is not a file.";
+  }
+
+  if (typeof body.sha !== "string" || body.sha.length === 0) {
+    return "GitHub returned a file without a sha.";
+  }
+
+  const size = typeof body.size === "number" ? body.size : 0;
+  if (body.content === undefined && size > GITHUB_INLINE_FILE_SIZE_LIMIT) {
+    return "File is too large for the GitHub Contents API (over 1 MB). SourceDraft v0.1 cannot read or publish this file inline.";
+  }
+
+  if (typeof body.content !== "string" || body.encoding !== "base64") {
+    return "GitHub did not return base64 file content.";
+  }
+
+  return null;
+}
+
+export function directoryListingLimitMessage(): string {
+  return (
+    "GitHub directory listing limit reached (1000 entries in one folder). " +
+    "SourceDraft v0.1 uses the Contents API, which is suitable for small and medium content folders. " +
+    "Very large sites may need a future Git Trees API or indexed listing implementation."
+  );
+}
+
+export function errorContextFromConfig(
+  config: { owner: string; repo: string },
+  extras: GitHubErrorContext = {},
+): GitHubErrorContext {
+  return {
+    owner: config.owner,
+    repo: config.repo,
+    ...extras,
+  };
+}
diff --git a/packages/github-publisher/src/githubPaths.test.ts b/packages/github-publisher/src/githubPaths.test.ts
new file mode 100644
index 0000000..e7cf798
--- /dev/null
+++ b/packages/github-publisher/src/githubPaths.test.ts
@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { encodeRepoPath, normalizeRepoPath } from "./githubPaths.js";
+
+describe("normalizeRepoPath", () => {
+  it("strips leading slashes and whitespace", () => {
+    assert.equal(normalizeRepoPath(" /src/content/blog/ "), "src/content/blog/");
+  });
+});
+
+describe("encodeRepoPath", () => {
+  it("encodes path segments for GitHub API URLs", () => {
+    assert.equal(encodeRepoPath("src/content/blog/post.mdx"), "src/content/blog/post.mdx");
+    assert.equal(encodeRepoPath("images/my photo.png"), "images/my%20photo.png");
+  });
+});
diff --git a/packages/github-publisher/src/githubPaths.ts b/packages/github-publisher/src/githubPaths.ts
new file mode 100644
index 0000000..751b8f5
--- /dev/null
+++ b/packages/github-publisher/src/githubPaths.ts
@@ -0,0 +1,11 @@
+export function normalizeRepoPath(path: string): string {
+  return path.trim().replace(/^\/+/u, "");
+}
+
+export function encodeRepoPath(path: string): string {
+  return path
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
diff --git a/packages/github-publisher/src/githubPublisher.ts b/packages/github-publisher/src/githubPublisher.ts
index e6a2e4a..46d2455 100644
--- a/packages/github-publisher/src/githubPublisher.ts
+++ b/packages/github-publisher/src/githubPublisher.ts
@@ -1,3 +1,22 @@
+/**
+ * GitHub Contents API publisher for SourceDraft v0.1.
+ *
+ * This MVP uses the Contents API for publish, list, read, and upload flows.
+ * It works well for small and medium content folders. Very large directories
+ * may hit GitHub listing limits; a future version may add Git Trees API or
+ * indexed listing for large sites.
+ */
+import {
+  directoryListingLimitMessage,
+  errorContextFromConfig,
+  formatGitHubApiError,
+  formatLocalGitHubError,
+  isDirectoryListingTruncated,
+  validateGitHubFileBody,
+  type GitHubOperation,
+} from "./githubErrors.js";
+import { encodeRepoPath, normalizeRepoPath } from "./githubPaths.js";
+
 const GITHUB_API_VERSION = "2022-11-28";
 
 export type GitHubPublisherConfig = {
@@ -10,6 +29,7 @@ export type GitHubPublisherConfig = {
 export type PublishFileInput = {
   path: string;
   message: string;
+  purpose?: "post" | "media";
 } & (
   | { content: string; contentBase64?: never }
   | { contentBase64: string; content?: never }
@@ -33,6 +53,7 @@ export type PublishFileResult = PublishFileSuccess | PublishFileError;
 
 export type ListFilesInput = {
   path: string;
+  contentDir?: string;
 };
 
 export type ListedFile = {
@@ -99,18 +120,6 @@ type GitHubCommitBody = {
   };
 };
 
-function normalizeRepoPath(path: string): string {
-  return path.replace(/^\/+/u, "").trim();
-}
-
-function encodeRepoPath(path: string): string {
-  return path
-    .split("/")
-    .filter((segment) => segment.length > 0)
-    .map((segment) => encodeURIComponent(segment))
-    .join("/");
-}
-
 function contentsUrl(config: GitHubPublisherConfig, path: string): string {
   const encodedPath = encodeRepoPath(path);
   return `https://api.github.com/repos/${config.owner}/${config.repo}/contents/${encodedPath}`;
@@ -137,6 +146,35 @@ async function readGitHubError(response: Response): Promise<string> {
   return response.statusText || "GitHub API request failed.";
 }
 
+function apiError(
+  response: Response,
+  rawMessage: string,
+  operation: GitHubOperation,
+  config: GitHubPublisherConfig,
+  context: { path?: string; contentDir?: string; mediaDir?: string } = {},
+): PublishFileError {
+  const errorContext = errorContextFromConfig(config, context);
+  return {
+    ok: false,
+    error: formatGitHubApiError(response.status, rawMessage, operation, errorContext),
+    status: response.status,
+  };
+}
+
+function localError(
+  message: string,
+  operation: GitHubOperation,
+  config: GitHubPublisherConfig,
+  context: { path?: string; contentDir?: string; mediaDir?: string } = {},
+  status?: number,
+): PublishFileError {
+  return {
+    ok: false,
+    error: formatLocalGitHubError(message, operation, errorContextFromConfig(config, context)),
+    ...(status !== undefined ? { status } : {}),
+  };
+}
+
 function encodeContent(content: string): string {
   return Buffer.from(content, "utf8").toString("base64");
 }
@@ -173,11 +211,13 @@ function resolvePublishContent(input: PublishFileInput): PublishFileError | stri
 async function getExistingFileSha(
   config: GitHubPublisherConfig,
   path: string,
+  purpose: "post" | "media",
 ): Promise<
   | { found: true; sha: string }
   | { found: false }
   | PublishFileError
 > {
+  const operation: GitHubOperation = purpose === "media" ? "uploadMedia" : "checkFile";
   const url = `${contentsUrl(config, path)}?ref=${encodeURIComponent(config.branch)}`;
   const response = await fetch(url, {
     method: "GET",
@@ -189,23 +229,33 @@ async function getExistingFileSha(
   }
 
   if (!response.ok) {
-    return {
-      ok: false,
-      error: await readGitHubError(response),
-      status: response.status,
-    };
+    const raw = await readGitHubError(response);
+    return apiError(response, raw, operation, config, { path });
   }
 
-  const body = (await response.json()) as GitHubContentBody;
-  if (typeof body.sha !== "string" || body.sha.length === 0) {
-    return {
-      ok: false,
-      error: "GitHub returned a file without a sha.",
-      status: response.status,
-    };
+  let body: GitHubContentBody | GitHubDirectoryEntry[];
+  try {
+    body = (await response.json()) as GitHubContentBody | GitHubDirectoryEntry[];
+  } catch {
+    return localError(
+      "GitHub returned an unreadable file response.",
+      operation,
+      config,
+      { path },
+      response.status,
+    );
+  }
+
+  if (Array.isArray(body)) {
+    return localError("Path is not a file.", operation, config, { path }, response.status);
   }
 
-  return { found: true, sha: body.sha };
+  const validationError = validateGitHubFileBody(body);
+  if (validationError !== null) {
+    return localError(validationError, operation, config, { path }, response.status);
+  }
+
+  return { found: true, sha: body.sha as string };
 }
 
 async function putFile(
@@ -213,8 +263,10 @@ async function putFile(
   path: string,
   contentBase64: string,
   message: string,
+  purpose: "post" | "media",
   existingSha?: string,
 ): Promise<PublishFileResult> {
+  const operation: GitHubOperation = purpose === "media" ? "uploadMedia" : "publish";
   const payload: Record<string, string> = {
     message,
     content: contentBase64,
@@ -235,31 +287,47 @@ async function putFile(
   });
 
   if (!response.ok) {
-    return {
-      ok: false,
-      error: await readGitHubError(response),
-      status: response.status,
-    };
+    const raw = await readGitHubError(response);
+    return apiError(response, raw, operation, config, {
+      path,
+      ...(purpose === "media" ? { mediaDir: path.split("/").slice(0, -1).join("/") } : {}),
+    });
+  }
+
+  let body: GitHubCommitBody;
+  try {
+    body = (await response.json()) as GitHubCommitBody;
+  } catch {
+    return localError(
+      "GitHub returned an unreadable publish response.",
+      operation,
+      config,
+      { path },
+      response.status,
+    );
   }
 
-  const body = (await response.json()) as GitHubCommitBody;
   const sha = body.content?.sha;
   const commitSha = body.commit?.sha;
 
   if (typeof sha !== "string" || sha.length === 0) {
-    return {
-      ok: false,
-      error: "GitHub did not return the published file sha.",
-      status: response.status,
-    };
+    return localError(
+      "GitHub did not return the published file sha.",
+      operation,
+      config,
+      { path },
+      response.status,
+    );
   }
 
   if (typeof commitSha !== "string" || commitSha.length === 0) {
-    return {
-      ok: false,
-      error: "GitHub did not return the commit sha.",
-      status: response.status,
-    };
+    return localError(
+      "GitHub did not return the commit sha.",
+      operation,
+      config,
+      { path },
+      response.status,
+    );
   }
 
   return {
@@ -274,6 +342,7 @@ async function putFile(
 async function collectFiles(
   config: GitHubPublisherConfig,
   path: string,
+  contentDir: string,
   files: ListedFile[],
 ): Promise<PublishFileError | null> {
   const url = `${contentsUrl(config, path)}?ref=${encodeURIComponent(config.branch)}`;
@@ -283,14 +352,25 @@ async function collectFiles(
   });
 
   if (!response.ok) {
-    return {
-      ok: false,
-      error: await readGitHubError(response),
-      status: response.status,
-    };
+    const raw = await readGitHubError(response);
+    return apiError(response, raw, "listPosts", config, {
+      path,
+      contentDir,
+    });
   }
 
-  const body = (await response.json()) as GitHubDirectoryEntry | GitHubDirectoryEntry[];
+  let body: GitHubDirectoryEntry | GitHubDirectoryEntry[];
+  try {
+    body = (await response.json()) as GitHubDirectoryEntry | GitHubDirectoryEntry[];
+  } catch {
+    return localError(
+      "GitHub returned an unreadable directory listing.",
+      "listPosts",
+      config,
+      { path, contentDir },
+      response.status,
+    );
+  }
 
   if (!Array.isArray(body)) {
     if (
@@ -306,9 +386,22 @@ async function collectFiles(
         sha: body.sha,
         size: body.size,
       });
+      return null;
     }
 
-    return null;
+    return localError(
+      `Could not list posts under "${contentDir}". contentDir should be a folder containing post files.`,
+      "listPosts",
+      config,
+      { path, contentDir },
+    );
+  }
+
+  if (isDirectoryListingTruncated(body.length)) {
+    return localError(directoryListingLimitMessage(), "listPosts", config, {
+      path,
+      contentDir,
+    });
   }
 
   for (const entry of body) {
@@ -332,7 +425,7 @@ async function collectFiles(
     }
 
     if (entry.type === "dir" && typeof entry.path === "string") {
-      const error = await collectFiles(config, entry.path, files);
+      const error = await collectFiles(config, entry.path, contentDir, files);
       if (error !== null) {
         return error;
       }
@@ -348,6 +441,8 @@ export function createGitHubPublisher(
   return {
     async publishFile(input: PublishFileInput): Promise<PublishFileResult> {
       const path = normalizeRepoPath(input.path);
+      const purpose = input.purpose ?? "post";
+
       if (path.length === 0) {
         return {
           ok: false,
@@ -367,7 +462,7 @@ export function createGitHubPublisher(
         return encodedContent;
       }
 
-      const existing = await getExistingFileSha(config, path);
+      const existing = await getExistingFileSha(config, path, purpose);
       if ("ok" in existing) {
         return existing;
       }
@@ -378,15 +473,18 @@ export function createGitHubPublisher(
           path,
           encodedContent,
           input.message,
+          purpose,
           existing.sha,
         );
       }
 
-      return putFile(config, path, encodedContent, input.message);
+      return putFile(config, path, encodedContent, input.message, purpose);
     },
 
     async listFiles(input: ListFilesInput): Promise<ListFilesResult> {
       const path = normalizeRepoPath(input.path);
+      const contentDir = input.contentDir ?? path;
+
       if (path.length === 0) {
         return {
           ok: false,
@@ -395,7 +493,7 @@ export function createGitHubPublisher(
       }
 
       const files: ListedFile[] = [];
-      const error = await collectFiles(config, path, files);
+      const error = await collectFiles(config, path, contentDir, files);
       if (error !== null) {
         return error;
       }
@@ -419,40 +517,33 @@ export function createGitHubPublisher(
       });
 
       if (!response.ok) {
-        return {
-          ok: false,
-          error: await readGitHubError(response),
-          status: response.status,
-        };
+        const raw = await readGitHubError(response);
+        return apiError(response, raw, "readPost", config, { path });
       }
 
-      const body = (await response.json()) as GitHubContentBody;
-      if (body.type !== "file") {
-        return {
-          ok: false,
-          error: "Path is not a file.",
-        };
-      }
-
-      if (typeof body.content !== "string" || body.encoding !== "base64") {
-        return {
-          ok: false,
-          error: "GitHub did not return base64 file content.",
-        };
+      let body: GitHubContentBody;
+      try {
+        body = (await response.json()) as GitHubContentBody;
+      } catch {
+        return localError(
+          "GitHub returned an unreadable file response.",
+          "readPost",
+          config,
+          { path },
+          response.status,
+        );
       }
 
-      if (typeof body.sha !== "string" || body.sha.length === 0) {
-        return {
-          ok: false,
-          error: "GitHub returned a file without a sha.",
-        };
+      const validationError = validateGitHubFileBody(body);
+      if (validationError !== null) {
+        return localError(validationError, "readPost", config, { path }, response.status);
       }
 
       return {
         ok: true,
         path,
-        content: Buffer.from(body.content, "base64").toString("utf8"),
-        sha: body.sha,
+        content: Buffer.from(body.content as string, "base64").toString("utf8"),
+        sha: body.sha as string,
       };
     },
   };
diff --git a/packages/github-publisher/src/index.ts b/packages/github-publisher/src/index.ts
index f50a100..884e59d 100644
--- a/packages/github-publisher/src/index.ts
+++ b/packages/github-publisher/src/index.ts
@@ -2,6 +2,15 @@ export {
   createGitHubPublisher,
 } from "./githubPublisher.js";
 
+export {
+  directoryListingLimitMessage,
+  formatGitHubApiError,
+  GITHUB_DIRECTORY_LISTING_LIMIT,
+  GITHUB_INLINE_FILE_SIZE_LIMIT,
+} from "./githubErrors.js";
+
+export { encodeRepoPath, normalizeRepoPath } from "./githubPaths.js";
+
 export type {
   GitHubPublisher,
   GitHubPublisherConfig,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 04d15a2..ccc0af4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -143,6 +143,9 @@ importers:
       '@types/node':
         specifier: ^22.15.30
         version: 22.19.19
+      tsx:
+        specifier: ^4.20.3
+        version: 4.22.4
       typescript:
         specifier: ^5.8.3
         version: 5.9.3