pythonnative
diff --git a/‎api/cli/index.html‎
Lines changed: 12 additions & 4 deletions b/‎api/cli/index.html‎
Lines changed: 12 additions & 4 deletions
diff --git a/‎getting-started/index.html‎
Lines changed: 9 additions & 7 deletions b/‎getting-started/index.html‎
Lines changed: 9 additions & 7 deletions
diff --git a/‎meta/troubleshooting/index.html‎
Lines changed: 33 additions & 0 deletions b/‎meta/troubleshooting/index.html‎
Lines changed: 33 additions & 0 deletions
diff --git a/‎search/search_index.json‎
Lines changed: 1 addition & 1 deletion b/‎search/search_index.json‎
Lines changed: 1 addition & 1 deletion
@@ -3335,7 +3335,8 @@ <h2 id="subcommands">Subcommands<a class="headerlink" href="#subcommands" title=
 <ul>
 <li><code>pn init [name]</code>: scaffold a new project (creates <code>app/</code>,
   <code>pythonnative.toml</code>, <code>.gitignore</code>). With a name it creates <code>./&lt;name&gt;/</code>
-  and scaffolds into it; without one it uses the current directory.
+  and scaffolds into it; the name must match <code>^[a-z][a-z0-9_-]*$</code>.
+  Without one it uses the current directory, whatever it's called.
   Flag: <code>--force</code> to overwrite existing files or scaffold into a
   non-empty directory. See <a href="../../guides/configuration/">Configuration</a>.</li>
 <li><code>pn doctor [android|ios]</code>: diagnose the local toolchain and validate
@@ -3586,9 +3587,16 @@ <h2 id="pythonnative.cli.pn.init_project" class="doc doc-heading">
 one, it scaffolds into the current directory and names the project after
 it. Either way it writes <code>app/main.py</code>, <code>pythonnative.toml</code>, and
 <code>.gitignore</code>.</p>
-<p>The name has to be a single directory name, so the project always lands
-inside the current directory. Anything that reads as a path, such as
-<code>a/b</code>, <code>..</code>, or <code>/tmp/app</code>, is refused, and so is a name that
+<p>A name you pass has to match <code>^[a-z][a-z0-9_-]*$</code>: lowercase letters,
+digits, <code>-</code>, and <code>_</code>, starting with a letter. Anything else is
+refused with a legal suggestion. That keeps the directory name and the
+<code>name</code> field in the generated config identical, in the same spirit as
+<code>flutter create</code> and <code>cargo new</code>. The name taken from the current
+directory when you pass none is used as-is, so an existing directory
+with any name still works.</p>
+<p>The name also has to be a single directory name, so the project always
+lands inside the current directory. Anything that reads as a path, such
+as <code>a/b</code>, <code>..</code>, or <code>/tmp/app</code>, is refused, and so is a name that
 resolves somewhere else, such as a symlink to another directory.</p>
 <p>It won't scaffold into a target directory that already holds files, and it
 won't overwrite any of the three paths above; pass <code>--force</code> to override
 
@@ -3241,19 +3241,21 @@ <h1 id="getting-started">Getting Started<a class="headerlink" href="#getting-sta
 </span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>pn<span class="w"> </span>--help
 </span></code></pre></div>
 <h2 id="create-a-project">Create a project<a class="headerlink" href="#create-a-project" title="Permanent link">&para;</a></h2>
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>pn<span class="w"> </span>init<span class="w"> </span>MyApp
-</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="nb">cd</span><span class="w"> </span>MyApp
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>pn<span class="w"> </span>init<span class="w"> </span>my_app
+</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="nb">cd</span><span class="w"> </span>my_app
 </span></code></pre></div>
-<p>This creates a <code>MyApp/</code> directory containing:</p>
+<p>This creates a <code>my_app/</code> directory containing:</p>
 <ul>
 <li><code>app/</code> with a minimal <code>main.py</code></li>
 <li><code>pythonnative.toml</code>: your project configuration (app id, version,
   permissions, assets, and signing). See
   <a href="../guides/configuration/">Configuration</a>.</li>
 <li><code>.gitignore</code></li>
 </ul>
-<p>Run <code>pn init</code> without a name to scaffold into the current directory
-instead, named after it.</p>
+<p>A name has to be lowercase letters, digits, <code>-</code>, and <code>_</code>, starting with
+a letter, so the directory name and the <code>name</code> field in the generated
+config stay identical. Run <code>pn init</code> without a name to scaffold into the
+current directory instead, named after it; that name is used as-is.</p>
 <p>A minimal <code>app/main.py</code> looks like:</p>
 <div class="language-python highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">import</span><span class="w"> </span><span class="nn">pythonnative</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">pn</span>
 </span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>
@@ -3304,8 +3306,8 @@ <h2 id="configure-your-app">Configure your app<a class="headerlink" href="#confi
 splash, third-party packages, and signing) lives in a single
 <code>pythonnative.toml</code> at the project root:</p>
 <div class="language-toml highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="k">[app]</span>
-</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="n">id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"com.example.myapp"</span>
-</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"myapp"</span>
+</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="n">id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"com.example.my_app"</span>
+</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"my_app"</span>
 </span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="n">display_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"My App"</span>
 </span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a><span class="n">version</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"1.0.0"</span>
 </span><span id="__span-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a><span class="n">build</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span>
 
@@ -3003,6 +3003,17 @@
     </span>
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#invalid-project-name-myapp" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Invalid project name: 'MyApp'
+      
+    </span>
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -3461,6 +3472,17 @@
     </span>
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#invalid-project-name-myapp" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Invalid project name: 'MyApp'
+      
+    </span>
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -3851,6 +3873,17 @@ <h3 id="refusing-to-treat-a-path-as-a-project-name-app"><code>Refusing to treat
 lands inside the current directory. Pass a plain name like <code>my_app</code>, or
 <code>cd</code> to the directory you want the project in and run <code>pn init</code> with no
 name at all. <code>--force</code> doesn't lift this one.</p>
+<h3 id="invalid-project-name-myapp"><code>Invalid project name: 'MyApp'</code><a class="headerlink" href="#invalid-project-name-myapp" title="Permanent link">&para;</a></h3>
+<p>A name you pass to <code>pn init</code> has to match <code>^[a-z][a-z0-9_-]*$</code>: lowercase
+letters, digits, <code>-</code>, and <code>_</code>, starting with a letter. That's the same
+spirit as <code>flutter create</code> and <code>cargo new</code>, and it keeps the directory
+name and the <code>name</code> field in the config identical. The error suggests a
+legal name you can paste straight back, so <code>MyApp</code> suggests <code>myapp</code> and
+<code>my app</code> suggests <code>my_app</code>. <code>--force</code> doesn't lift this one.</p>
+<p>This applies only to a name you type. <code>pn init</code> with no name takes the
+current directory's name as-is, so a directory called <code>MyProject</code> is
+fine. To use a display name outside this set, edit <code>display_name</code> in
+<code>pythonnative.toml</code> after scaffolding.</p>
 <h3 id="refusing-to-scaffold-through-a-link-or-outside-the-current-directory-link"><code>Refusing to scaffold through a link or outside the current directory: link</code><a class="headerlink" href="#refusing-to-scaffold-through-a-link-or-outside-the-current-directory-link" title="Permanent link">&para;</a></h3>
 <p>The name resolves somewhere other than a directory directly inside the
 current one, so <code>pn init</code> stops rather than writing through it. A symlink