diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml
new file mode 100644
index 00000000..2717f1e5
--- /dev/null
+++ b/.github/codeql/codeql-config.yml
@@ -0,0 +1,13 @@
+name: ConvNetJS Security Scanning
+rules:
+  - query: security-and-quality
+  - query: security-extended
+  - query: security-audit
+  - query: experimental
+  - query: performance
+
+exclude:
+  - path: test/**
+  - path: demo/**
+  - path: build/**
+  - path: compile/**
diff --git a/.github/scripts/security-review.js b/.github/scripts/security-review.js
new file mode 100644
index 00000000..674f479f
--- /dev/null
+++ b/.github/scripts/security-review.js
@@ -0,0 +1,158 @@
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const sarifPath = process.argv[2] || 'results.sarif';
+const reportPath = process.argv[3] || 'security-report.md';
+const openAiKey = process.env.OPENAI_API_KEY;
+const openAiModel = process.env.OPENAI_MODEL || 'gpt-4o-mini';
+
+function loadSarif(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`SARIF file not found: ${filePath}`);
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function summarizeFindings(results) {
+  const severityOrder = ['error', 'warning', 'note', 'none'];
+  const severityCounts = results.reduce((acc, item) => {
+    const severity = (item.level || item.kind || 'warning').toLowerCase();
+    acc[severity] = (acc[severity] || 0) + 1;
+    return acc;
+  }, {});
+
+  const byRule = results.reduce((acc, item) => {
+    const ruleId = item.ruleId || 'unknown';
+    acc[ruleId] = acc[ruleId] || { count: 0, message: [] };
+    acc[ruleId].count += 1;
+    if (item.message && item.message.text) acc[ruleId].message.push(item.message.text);
+    return acc;
+  }, {});
+
+  return { severityCounts, byRule };
+}
+
+function formatReport(sarif, summary, topFindings) {
+  const totalFindings = topFindings.length;
+  const severityLines = Object.entries(summary.severityCounts)
+    .sort(([a], [b]) => severityOrder.indexOf(a) - severityOrder.indexOf(b))
+    .map(([level, count]) => `- **${level}**: ${count}`)
+    .join('\n');
+
+  const findingLines = topFindings.map((item, index) => {
+    const location = item.locations && item.locations[0] && item.locations[0].physicalLocation;
+    const file = location && location.artifactLocation && location.artifactLocation.uri;
+    const region = location && location.region;
+    const line = region ? region.startLine : 'N/A';
+    return [`### Finding ${index + 1}`,
+      `- **Rule**: ${item.ruleId || 'unknown'}`,
+      `- **Severity**: ${item.level || item.kind || 'warning'}`,
+      `- **Message**: ${item.message && item.message.text ? item.message.text : 'N/A'}`,
+      `- **Location**: ${file || 'unknown'}:${line}`,
+      ''].join('\n');
+  }).join('\n');
+
+  return [`# Security Report`,
+    '',
+    `## Summary`,
+    '',
+    `- Total findings: **${totalFindings}**`,
+    severityLines ? `\n${severityLines}` : '',
+    '',
+    `## Top Findings`,
+    '',
+    findingLines || 'No findings detected.',
+    '',
+    `## Review Notes`,
+    '',
+    `The report was generated automatically by the GitHub Actions DevSecOps pipeline.`,
+    openAiKey ? `An LLM review was requested and its analysis is included below.` : `LLM review was skipped because OPENAI_API_KEY is not configured.`,
+    '',
+    `---`,
+    '',
+    `*Generated by the DevSecOps pipeline.*`].join('\n');
+}
+
+function extractTopFindings(results, max = 8) {
+  return results.slice(0, max);
+}
+
+async function callOpenAI(prompt) {
+  const body = JSON.stringify({
+    model: openAiModel,
+    messages: [{ role: 'system', content: 'Você é um assistente de segurança de software. Revise os resultados SARIF e gere um resumo conciso com risco, gravidade e recomendações.' },
+               { role: 'user', content: prompt }],
+    max_tokens: 500,
+    temperature: 0.2
+  });
+
+  const options = {
+    hostname: 'api.openai.com',
+    path: '/v1/chat/completions',
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${openAiKey}`,
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body)
+    }
+  };
+
+  return new Promise((resolve, reject) => {
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => data += chunk);
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            const json = JSON.parse(data);
+            const content = json.choices && json.choices[0] && json.choices[0].message && json.choices[0].message.content;
+            resolve(content || 'LLM review completed but no content was returned.');
+          } catch (error) {
+            reject(new Error(`Falha ao analisar retorno do OpenAI: ${error.message}`));
+          }
+        } else {
+          reject(new Error(`OpenAI API error ${res.statusCode}: ${data}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+async function main() {
+  const sarif = loadSarif(sarifPath);
+  const results = (sarif.runs || []).flatMap(run => run.results || []);
+  const summary = summarizeFindings(results);
+  const topFindings = extractTopFindings(results);
+  let report = formatReport(sarif, summary, topFindings);
+
+  if (openAiKey && results.length > 0) {
+    const prompt = `Aqui estão os ${results.length} resultados SARIF mais importantes. Forneça um resumo de risco, explique os impactos e indique ações corretivas relevantes. Exiba como listas claras e concisas. \n\n` +
+      topFindings.map((item, index) => {
+        const location = item.locations && item.locations[0] && item.locations[0].physicalLocation;
+        const file = location && location.artifactLocation && location.artifactLocation.uri;
+        const region = location && location.region;
+        const line = region ? region.startLine : 'N/A';
+        return `${index + 1}. Rule: ${item.ruleId || 'unknown'}; Severity: ${item.level || item.kind || 'warning'}; File: ${file || 'unknown'}:${line}; Message: ${item.message && item.message.text ? item.message.text : 'N/A'}`;
+      }).join('\n');
+
+    try {
+      const llmReview = await callOpenAI(prompt);
+      report += '\n\n## LLM Review\n\n' + llmReview + '\n';
+    } catch (error) {
+      report += `\n\n## LLM Review\n\nFalha ao obter análise LLM: ${error.message}\n`;
+    }
+  }
+
+  fs.writeFileSync(reportPath, report, 'utf8');
+  console.log(`Security report written to ${reportPath}`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/.github/workflows/devsecops-security.yml b/.github/workflows/devsecops-security.yml
new file mode 100644
index 00000000..37c4f34b
--- /dev/null
+++ b/.github/workflows/devsecops-security.yml
@@ -0,0 +1,95 @@
+name: DevSecOps Security Pipeline
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - develop
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+  schedule:
+    - cron: '0 3 * * *'
+
+jobs:
+  codeql:
+    name: CodeQL SAST Scan
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+      #analysis: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: javascript
+          config-file: .github/codeql/codeql-config.yml
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          output: results.sarif
+
+      - name: Upload SARIF artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: codeql-sarif
+          path: results.sarif
+
+  security_review:
+    name: LLM Security Review & PR Comment
+    runs-on: ubuntu-latest
+    needs: codeql
+    if: always()
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download SARIF artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: codeql-sarif
+
+      - name: Generate security report
+        run: |
+          node .github/scripts/security-review.js results.sarif security-report.md
+
+      - name: Upload security report artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-report
+          path: security-report.md
+
+      - name: Create automatic security report pull request
+        if: github.event_name != 'pull_request'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "docs: update automated security report"
+          title: "docs: update automated security report"
+          body: |
+            This pull request was generated automatically by the DevSecOps Security Pipeline.
+
+            It updates the generated `security-report.md` file from the latest CodeQL SARIF results.
+          branch: automated/security-report
+          base: ${{ github.ref_name }}
+          add-paths: security-report.md
+          labels: security, automated-pr
+
+      - name: Comment on pull request
+        if: github.event_name == 'pull_request'
+        uses: peter-evans/create-or-update-comment@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body-file: security-report.md
+          edit-mode: replace
diff --git a/demo/autoencoder.html b/demo/autoencoder.html
index e2d37f18..234c8ca1 100644
--- a/demo/autoencoder.html
+++ b/demo/autoencoder.html
@@ -13,6 +13,7 @@
 <script src="../build/vis.js"></script>
 <script src="../build/util.js"></script>
 <script src="../build/convnet.js"></script>
+<script src="js/safe-config.js"></script>
 
 
 <script src="mnist/mnist_labels.js"></script>
diff --git a/demo/cifar10.html b/demo/cifar10.html
index a8a1594a..80ac0b5b 100644
--- a/demo/cifar10.html
+++ b/demo/cifar10.html
@@ -12,6 +12,7 @@
 <script src="../build/vis.js"></script>
 <script src="../build/util.js"></script>
 <script src="../build/convnet.js"></script>
+<script src="js/safe-config.js"></script>
 
 <script src="js/image-helpers.js"></script>
 <script src="js/pica.js"></script>
diff --git a/demo/classify2d.html b/demo/classify2d.html
index c933ae6c..cf601aef 100644
--- a/demo/classify2d.html
+++ b/demo/classify2d.html
@@ -7,6 +7,7 @@
 <script src="js/npgmain.js"></script>
 <script src="../build/convnet.js"></script>
 <script src="../build/util.js"></script>
+<script src="js/safe-config.js"></script>
 <script src="js/classify2d.js"></script>
 
 <style type="text/css">
@@ -50,7 +51,7 @@ <h1><a href="http://cs.stanford.edu/people/karpathy/convnetjs">ConvnetJS</a> dem
 <br>
 <input id="buttontp" type="submit" value="change network" onclick="reload();" style="width: 300px; height: 50px;"/>
 
-<p>Feel free to change this, the text area above gets eval()'d when you hit the button and the network gets reloaded. Every 10th of a second, all points are fed to the network multiple times through the trainer class to train the network. The resulting predictions of the network are then "painted" under the data points to show you the generalization.</p>
+<p>Feel free to change this, the text area above is parsed as a restricted ConvNetJS configuration when you hit the button and the network gets reloaded. Every 10th of a second, all points are fed to the network multiple times through the trainer class to train the network. The resulting predictions of the network are then "painted" under the data points to show you the generalization.</p>
 
 <p>On the right we visualize the transformed representation of all grid points in the original space and the data, for a given layer and only for 2 neurons at a time. The number in the bracket shows the total number of neurons at that level of representation. If the number is more than 2, you will only see the two visualized but you can cycle through all of them with the cycle button.</p>
 
diff --git a/demo/image_regression.html b/demo/image_regression.html
index a8ae7e17..68dc6a9a 100644
--- a/demo/image_regression.html
+++ b/demo/image_regression.html
@@ -9,6 +9,7 @@
 <script src="js/jquery-ui.min.js"></script>
 
 <script src="../build/convnet.js"></script>
+<script src="js/safe-config.js"></script>
 <script src="js/image_regression.js"></script>
 
 <style type="text/css">
@@ -38,7 +39,7 @@ <h1><a href="http://cs.stanford.edu/people/karpathy/convnetjs/">ConvnetJS</a> de
 
 <p>This demo that treats the pixels of an image as a learning problem: it takes the (x,y) position on a grid and learns to predict the color at that point using regression to (r,g,b). It's a bit like compression, since the image information is encoded in the weights of the network, but almost certainly not of practical kind :)</p>
 <p>
-  Note that the entire ConvNetJS definition is shown in textbox below and it gets eval()'d to create the network, so feel free to fiddle with the parameters and hit "reload". I found that, empirically and interestingly, deeper networks tend to work much better on this task given a fixed parameter budget.
+  Note that the entire ConvNetJS definition is shown in textbox below and it is parsed as a restricted configuration to create the network, so feel free to fiddle with the parameters and hit "reload". I found that, empirically and interestingly, deeper networks tend to work much better on this task given a fixed parameter budget.
 </p>
 
 <p>Report questions/bugs/suggestions to <a href="https://twitter.com/karpathy">@karpathy</a>.</p>
diff --git a/demo/js/autoencoder.js b/demo/js/autoencoder.js
index 9760312b..bd6d69ac 100644
--- a/demo/js/autoencoder.js
+++ b/demo/js/autoencoder.js
@@ -490,6 +490,9 @@ var load_from_json = function() {
   reset_all();
 }
 var change_net = function() {
-  eval($("#newnet").val());
+  var config = convnetjs.demoConfig.parseNetwork($("#newnet").val());
+  layer_defs = config.layer_defs;
+  net = config.net;
+  trainer = config.trainer;
   reset_all();
 }
diff --git a/demo/js/classify2d.js b/demo/js/classify2d.js
index 80332c8c..30ba2ba5 100644
--- a/demo/js/classify2d.js
+++ b/demo/js/classify2d.js
@@ -18,7 +18,10 @@ trainer = new convnetjs.SGDTrainer(net, {learning_rate:0.01, momentum:0.1, batch
 ";
 
 function reload() {
-  eval($("#layerdef").val());
+  var config = convnetjs.demoConfig.parseNetwork($("#layerdef").val());
+  layer_defs = config.layer_defs;
+  net = config.net;
+  trainer = config.trainer;
 
   // enter buttons for layers
   var t = '';
@@ -318,4 +321,4 @@ $(function() {
     reload();
     NPGinit(20);
 
-});
\ No newline at end of file
+});
diff --git a/demo/js/image_regression.js b/demo/js/image_regression.js
index 23bebd11..9f8dd806 100644
--- a/demo/js/image_regression.js
+++ b/demo/js/image_regression.js
@@ -95,7 +95,10 @@ function tick() {
 
 function reload() {
   counter = 0;
-  eval($("#layerdef").val());
+  var config = convnetjs.demoConfig.parseNetwork($("#layerdef").val());
+  layer_defs = config.layer_defs;
+  net = config.net;
+  trainer = config.trainer;
   //$("#slider").slider("value", Math.log(trainer.learning_rate) / Math.LN10);
   //$("#lr").html('Learning rate: ' + trainer.learning_rate);
 }
diff --git a/demo/js/images-demo.js b/demo/js/images-demo.js
index f8308726..dd6ed58d 100644
--- a/demo/js/images-demo.js
+++ b/demo/js/images-demo.js
@@ -105,7 +105,10 @@ var loaded_train_batches = [];
 $(window).load(function() {
 
   $("#newnet").val(t);
-  eval($("#newnet").val());
+  var config = convnetjs.demoConfig.parseNetwork($("#newnet").val());
+  layer_defs = config.layer_defs;
+  net = config.net;
+  trainer = config.trainer;
 
   update_net_param_display();
 
@@ -646,6 +649,9 @@ var load_pretrained = function() {
 }
 
 var change_net = function() {
-  eval($("#newnet").val());
+  var config = convnetjs.demoConfig.parseNetwork($("#newnet").val());
+  layer_defs = config.layer_defs;
+  net = config.net;
+  trainer = config.trainer;
   reset_all();
 }
diff --git a/demo/js/regression.js b/demo/js/regression.js
index 807fc69b..66dfedda 100644
--- a/demo/js/regression.js
+++ b/demo/js/regression.js
@@ -19,7 +19,10 @@ trainer = new convnetjs.SGDTrainer(net, {learning_rate:0.01, momentum:0.0, batch
 
 var lix=2; // layer id of layer we'd like to draw outputs of
 function reload() {
-  eval($("#layerdef").val());
+  var config = convnetjs.demoConfig.parseNetwork($("#layerdef").val());
+  layer_defs = config.layer_defs;
+  net = config.net;
+  trainer = config.trainer;
 
   // refresh buttons
   var t = '';
@@ -156,4 +159,4 @@ function keyUp(key) {
 
 $(function() {
     
-});
\ No newline at end of file
+});
diff --git a/demo/js/rldemo.js b/demo/js/rldemo.js
index 5636c1f2..076ef841 100644
--- a/demo/js/rldemo.js
+++ b/demo/js/rldemo.js
@@ -302,8 +302,7 @@
       // braaain
       //this.brain = new deepqlearn.Brain(this.eyes.length * 3, this.actions.length);
       var spec = document.getElementById('qspec').value;
-      eval(spec);
-      this.brain = brain;
+      this.brain = convnetjs.demoConfig.parseDeepQ(spec).brain;
       
       this.reward_bonus = 0.0;
       this.digestion_signal = 0.0;
@@ -575,4 +574,4 @@
       w.agents = [new Agent()];
       
       gofast();
-    }
\ No newline at end of file
+    }
diff --git a/demo/js/safe-config.js b/demo/js/safe-config.js
new file mode 100644
index 00000000..95bc9e49
--- /dev/null
+++ b/demo/js/safe-config.js
@@ -0,0 +1,289 @@
+(function(global) {
+  "use strict";
+
+  var convnetjs = global.convnetjs || {};
+
+  function ConfigError(message) {
+    this.name = "ConfigError";
+    this.message = message;
+  }
+  ConfigError.prototype = new Error();
+
+  function stripComments(source) {
+    var out = "";
+    var quote = null;
+    for(var i = 0; i < source.length; i++) {
+      var c = source.charAt(i);
+      var n = source.charAt(i + 1);
+      if(quote) {
+        out += c;
+        if(c === "\\" && i + 1 < source.length) {
+          i++;
+          out += source.charAt(i);
+        } else if(c === quote) {
+          quote = null;
+        }
+      } else if(c === "'" || c === '"') {
+        quote = c;
+        out += c;
+      } else if(c === "/" && n === "/") {
+        while(i < source.length && source.charAt(i) !== "\n") i++;
+        out += "\n";
+      } else if(c === "/" && n === "*") {
+        i += 2;
+        while(i < source.length && !(source.charAt(i) === "*" && source.charAt(i + 1) === "/")) i++;
+        i++;
+      } else {
+        out += c;
+      }
+    }
+    return out;
+  }
+
+  function splitStatements(source) {
+    var statements = [];
+    var start = 0;
+    var depth = 0;
+    var quote = null;
+    for(var i = 0; i < source.length; i++) {
+      var c = source.charAt(i);
+      if(quote) {
+        if(c === "\\" && i + 1 < source.length) i++;
+        else if(c === quote) quote = null;
+      } else if(c === "'" || c === '"') {
+        quote = c;
+      } else if(c === "{" || c === "[" || c === "(") {
+        depth++;
+      } else if(c === "}" || c === "]" || c === ")") {
+        depth--;
+      } else if(c === ";" && depth === 0) {
+        var statement = source.substring(start, i).replace(/^\s+|\s+$/g, "");
+        if(statement) statements.push(statement);
+        start = i + 1;
+      }
+    }
+    var last = source.substring(start).replace(/^\s+|\s+$/g, "");
+    if(last) statements.push(last);
+    return statements;
+  }
+
+  function Parser(source, scope) {
+    this.source = source;
+    this.i = 0;
+    this.scope = scope;
+  }
+
+  Parser.prototype = {
+    peek: function() { return this.source.charAt(this.i); },
+    skip: function() {
+      while(/\s/.test(this.peek())) this.i++;
+    },
+    expect: function(c) {
+      this.skip();
+      if(this.peek() !== c) throw new ConfigError("Expected '" + c + "' at column " + this.i);
+      this.i++;
+    },
+    parseIdentifier: function() {
+      this.skip();
+      var start = this.i;
+      if(!/[A-Za-z_$]/.test(this.peek())) throw new ConfigError("Expected identifier at column " + this.i);
+      this.i++;
+      while(/[A-Za-z0-9_$]/.test(this.peek())) this.i++;
+      return this.source.substring(start, this.i);
+    },
+    parseString: function() {
+      this.skip();
+      var quote = this.peek();
+      if(quote !== "'" && quote !== '"') throw new ConfigError("Expected string at column " + this.i);
+      this.i++;
+      var out = "";
+      while(this.i < this.source.length) {
+        var c = this.source.charAt(this.i++);
+        if(c === "\\") {
+          if(this.i < this.source.length) out += this.source.charAt(this.i++);
+        } else if(c === quote) {
+          return out;
+        } else {
+          out += c;
+        }
+      }
+      throw new ConfigError("Unterminated string literal");
+    },
+    parseNumber: function() {
+      this.skip();
+      var match = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/i.exec(this.source.substring(this.i));
+      if(!match) throw new ConfigError("Expected number at column " + this.i);
+      this.i += match[0].length;
+      return parseFloat(match[0]);
+    },
+    parseArray: function() {
+      var arr = [];
+      this.expect("[");
+      this.skip();
+      if(this.peek() === "]") { this.i++; return arr; }
+      while(true) {
+        arr.push(this.parseExpression());
+        this.skip();
+        if(this.peek() === "]") { this.i++; return arr; }
+        this.expect(",");
+      }
+    },
+    parseObject: function() {
+      var obj = {};
+      this.expect("{");
+      this.skip();
+      if(this.peek() === "}") { this.i++; return obj; }
+      while(true) {
+        this.skip();
+        var key = (this.peek() === "'" || this.peek() === '"') ? this.parseString() : this.parseIdentifier();
+        this.expect(":");
+        obj[key] = this.parseExpression();
+        this.skip();
+        if(this.peek() === "}") { this.i++; return obj; }
+        this.expect(",");
+      }
+    },
+    resolveIdentifier: function(name) {
+      if(name === "true") return true;
+      if(name === "false") return false;
+      if(name === "null") return null;
+      if(Object.prototype.hasOwnProperty.call(this.scope, name)) return this.scope[name];
+      throw new ConfigError("Unknown identifier: " + name);
+    },
+    parsePrimary: function() {
+      this.skip();
+      var c = this.peek();
+      if(c === "'" || c === '"') return this.parseString();
+      if(c === "[") return this.parseArray();
+      if(c === "{") return this.parseObject();
+      if(c === "(") {
+        this.i++;
+        var value = this.parseExpression();
+        this.expect(")");
+        return value;
+      }
+      if(/[+\-\d.]/.test(c)) return this.parseNumber();
+      return this.resolveIdentifier(this.parseIdentifier());
+    },
+    parseMul: function() {
+      var value = this.parsePrimary();
+      while(true) {
+        this.skip();
+        var op = this.peek();
+        if(op !== "*" && op !== "/") return value;
+        this.i++;
+        var right = this.parsePrimary();
+        value = op === "*" ? value * right : value / right;
+      }
+    },
+    parseExpression: function() {
+      var value = this.parseMul();
+      while(true) {
+        this.skip();
+        var op = this.peek();
+        if(op !== "+" && op !== "-") return value;
+        this.i++;
+        var right = this.parseMul();
+        value = op === "+" ? value + right : value - right;
+      }
+    }
+  };
+
+  function parseExpression(source, scope) {
+    var parser = new Parser(source, scope);
+    var value = parser.parseExpression();
+    parser.skip();
+    if(parser.i !== source.length) throw new ConfigError("Unexpected token at column " + parser.i);
+    return value;
+  }
+
+  function splitArgs(source) {
+    return splitStatements(source.replace(/,/g, ";"));
+  }
+
+  function execute(source, options) {
+    options = options || {};
+    var scope = {};
+    var statements = splitStatements(stripComments(source));
+
+    for(var i = 0; i < statements.length; i++) {
+      var s = statements[i];
+      var m;
+
+      m = /^(?:var\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*new\s+convnetjs\.Net\(\)$/.exec(s);
+      if(m) { scope[m[1]] = new convnetjs.Net(); continue; }
+
+      m = /^(?:var\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*new\s+convnetjs\.(?:SGDTrainer|Trainer)\(([^,]+),(.+)\)$/.exec(s);
+      if(m) {
+        scope[m[1]] = new convnetjs.SGDTrainer(scope[m[2].replace(/\s/g, "")], parseExpression(m[3], scope));
+        continue;
+      }
+
+      m = /^(?:var\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*new\s+deepqlearn\.Brain\((.+)\)$/.exec(s);
+      if(m) {
+        if(!global.deepqlearn || !global.deepqlearn.Brain) throw new ConfigError("deepqlearn.Brain is not available");
+        var args = splitArgs(m[2]);
+        scope[m[1]] = new global.deepqlearn.Brain(
+          parseExpression(args[0], scope),
+          parseExpression(args[1], scope),
+          args.length > 2 ? parseExpression(args[2], scope) : undefined
+        );
+        continue;
+      }
+
+      m = /^([A-Za-z_$][A-Za-z0-9_$]*)\.makeLayers\(([^)]+)\)$/.exec(s);
+      if(m) {
+        if(!scope[m[1]]) throw new ConfigError("Unknown network: " + m[1]);
+        scope[m[1]].makeLayers(parseExpression(m[2], scope));
+        continue;
+      }
+
+      m = /^([A-Za-z_$][A-Za-z0-9_$]*)\.push\((.+)\)$/.exec(s);
+      if(m) {
+        if(!scope[m[1]] || !scope[m[1]].push) throw new ConfigError("Cannot push into: " + m[1]);
+        scope[m[1]].push(parseExpression(m[2], scope));
+        continue;
+      }
+
+      m = /^([A-Za-z_$][A-Za-z0-9_$]*)\.([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(.+)$/.exec(s);
+      if(m) {
+        if(!scope[m[1]]) scope[m[1]] = {};
+        scope[m[1]][m[2]] = parseExpression(m[3], scope);
+        continue;
+      }
+
+      m = /^(?:var\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(.+)$/.exec(s);
+      if(m) {
+        scope[m[1]] = parseExpression(m[2], scope);
+        continue;
+      }
+
+      throw new ConfigError("Unsupported configuration statement: " + s);
+    }
+
+    if(options.requireNet && !scope.net) throw new ConfigError("Configuration did not create net");
+    if(options.requireTrainer && !scope.trainer) throw new ConfigError("Configuration did not create trainer");
+    if(options.requireBrain && !scope.brain) throw new ConfigError("Configuration did not create brain");
+    return scope;
+  }
+
+  convnetjs.demoConfig = {
+    ConfigError: ConfigError,
+    execute: execute,
+    parseNetwork: function(source) {
+      return execute(source, {requireNet: true, requireTrainer: true});
+    },
+    parseTrainerComparison: function(source) {
+      var scope = execute(source);
+      if(!scope.layer_defs || !scope.trainer_defs || !scope.legend) {
+        throw new ConfigError("Trainer comparison config requires layer_defs, trainer_defs and legend");
+      }
+      return scope;
+    },
+    parseDeepQ: function(source) {
+      return execute(source, {requireBrain: true});
+    }
+  };
+
+  global.convnetjs = convnetjs;
+})(this);
diff --git a/demo/js/trainers.js b/demo/js/trainers.js
index a280ef47..ba68f837 100644
--- a/demo/js/trainers.js
+++ b/demo/js/trainers.js
@@ -106,7 +106,10 @@ $(window).load(function() {
 
 var reload = function() {
   
-  eval($("#layerdef").val()); // fills in trainer_spects[] array, and layer_defs
+  var config = convnetjs.demoConfig.parseTrainerComparison($("#layerdef").val());
+  layer_defs = config.layer_defs;
+  trainer_defs = config.trainer_defs;
+  legend = config.legend;
 
   var N = trainer_defs.length;
   nets = [];
diff --git a/demo/mnist.html b/demo/mnist.html
index bc3aa74c..c5db2917 100644
--- a/demo/mnist.html
+++ b/demo/mnist.html
@@ -12,6 +12,7 @@
 <script src="../build/vis.js"></script>
 <script src="../build/util.js"></script>
 <script src="../build/convnet.js"></script>
+<script src="js/safe-config.js"></script>
 
 <script src="js/image-helpers.js"></script>
 <script src="js/pica.js"></script>
diff --git a/demo/regression.html b/demo/regression.html
index de7e13c4..cfa34f15 100644
--- a/demo/regression.html
+++ b/demo/regression.html
@@ -18,6 +18,7 @@
 <script src="js/jquery-1.8.3.min.js"></script>
 <script src="js/npgmain.js"></script>
 <script src="../build/convnet.js"></script>
+<script src="js/safe-config.js"></script>
 <script src="js/regression.js"></script>
 
 <style type="text/css">
@@ -42,7 +43,7 @@ <h1><a href="http://cs.stanford.edu/people/karpathy/convnetjs">ConvnetJS</a> dem
 
 <p>The simulation below is a 1-dimensional regression where a neural network is trained to regress to y coordinates for every given point x through an L2 loss. That is, the minimized cost function computes the squared difference between the predicted y-coordinate and the "correct" y coordinate. Every 10th of a second, all points are fed to the network multiple times through the trainer class to train the network.</p>
 
-<p>The simulation below will eval() whatever you have in the text area and reload. Feel free to explore and use ConvNetJS to instantiate your own network!</p>
+<p>The simulation below parses the text area as a restricted ConvNetJS configuration and reloads the network. Feel free to explore and use ConvNetJS to instantiate your own network!</p>
 
 <p>Report questions/bugs/suggestions to <a href="https://twitter.com/karpathy">@karpathy</a>.</p>
 
diff --git a/demo/rldemo.html b/demo/rldemo.html
index dac859f8..89fcba46 100644
--- a/demo/rldemo.html
+++ b/demo/rldemo.html
@@ -9,10 +9,11 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
   <script src="../build/convnet.js"></script>
-  <script src="../build/util.js"></script>
-  <script src="../build/vis.js"></script>
-  <script src="../build/deepqlearn.js"></script>
-  <link rel="stylesheet" href="css/style.css">
+  <script src="../build/util.js"></script>
+  <script src="../build/vis.js"></script>
+  <script src="../build/deepqlearn.js"></script>
+  <script src="js/safe-config.js"></script>
+  <link rel="stylesheet" href="css/style.css">
   
   <script src="js/rldemo.js"></script>
   <style type="text/css">
@@ -45,7 +46,7 @@ <h1>Description</h1>
    </p>
    <h1>Q-Learner full specification and options</h1>
    <p>
-   The textfield below gets eval()'d to produce the Q-learner for this demo. This allows you to fiddle with 
+   The textfield below is parsed as a restricted configuration to produce the Q-learner for this demo. This allows you to fiddle with 
    various parameters and settings and also shows how you can use the API for your own purposes. 
    All of these settings are optional but are listed to give an idea of possibilities.
    Feel free to change things around and hit reload! Documentation for all
diff --git a/demo/trainers.html b/demo/trainers.html
index 50e96949..276fb083 100644
--- a/demo/trainers.html
+++ b/demo/trainers.html
@@ -12,6 +12,7 @@
 <script src="../build/vis.js"></script>
 <script src="../build/util.js"></script>
 <script src="../build/convnet.js"></script>
+<script src="js/safe-config.js"></script>
 <script src="mnist/mnist_labels.js"></script>
 <script src="js/trainers.js"></script>
 
diff --git a/docs/casos-de-uso.md b/docs/casos-de-uso.md
new file mode 100644
index 00000000..533f4804
--- /dev/null
+++ b/docs/casos-de-uso.md
@@ -0,0 +1,250 @@
+# Casos de Uso
+
+## 1. Visao Geral
+
+Este documento descreve os principais casos de uso do ConvNetJS, considerando sua natureza de biblioteca JavaScript para redes neurais e seus exemplos estaticos em navegador.
+
+## 2. Atores
+
+| Ator | Descricao |
+| --- | --- |
+| Desenvolvedor JavaScript | Usa a API da biblioteca para criar, treinar e executar redes neurais. |
+| Estudante/Pesquisador | Explora conceitos de Deep Learning e aprendizado por reforco. |
+| Usuario de demo | Acessa exemplos HTML/JS prontos no navegador. |
+| Mantenedor | Mantem, testa, compila e distribui o projeto. |
+| Integrador | Incorpora o bundle ou export CommonJS em outro projeto. |
+
+## 3. Lista de Casos de Uso
+
+| ID | Nome | Ator principal | Requisitos relacionados |
+| --- | --- | --- | --- |
+| UC-01 | Definir rede neural | Desenvolvedor JavaScript | RF-01, RF-02, RF-03, RF-04, RF-05, RF-06, RF-07, RF-08 |
+| UC-02 | Treinar modelo | Desenvolvedor JavaScript | RF-10, RF-11 |
+| UC-03 | Executar inferencia | Desenvolvedor JavaScript | RF-09, RF-12, RF-14 |
+| UC-04 | Usar CNN com imagem | Desenvolvedor JavaScript | RF-04, RF-05, RF-14, RF-15 |
+| UC-05 | Serializar e restaurar rede | Integrador | RF-13 |
+| UC-06 | Executar demo no navegador | Usuario de demo | RF-18, RNF-01, RNF-05 |
+| UC-07 | Compilar biblioteca | Mantenedor | RF-19, RNF-03, RNF-04 |
+| UC-08 | Rodar testes Jasmine | Mantenedor | RF-20, RNF-07 |
+| UC-09 | Experimentar Deep Q Learning | Estudante/Pesquisador | RF-21 |
+
+## 4. Especificacao dos Casos de Uso
+
+### UC-01 - Definir rede neural
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Desenvolvedor JavaScript |
+| Objetivo | Criar uma rede neural a partir de uma lista ordenada de camadas. |
+| Pre-condicoes | A biblioteca ConvNetJS esta carregada no ambiente de execucao. |
+| Pos-condicoes | A instancia de `Net` contem as camadas criadas e esta pronta para inferencia ou treinamento. |
+
+Fluxo principal:
+
+1. O ator instancia `convnetjs.Net`.
+2. O ator cria uma lista de definicoes de camadas iniciada por `input`.
+3. O ator adiciona camadas intermediarias, como `fc`, `conv`, `pool`, ativacoes, dropout ou normalizacao.
+4. O ator adiciona uma camada final adequada, como `softmax`, `svm` ou `regression`.
+5. O ator chama `makeLayers` com a lista de camadas.
+6. A biblioteca cria a sequencia interna de camadas e calcula dimensoes de entrada e saida.
+
+Fluxos alternativos:
+
+- Se a lista possuir menos de duas camadas, a biblioteca deve indicar configuracao invalida.
+- Se a primeira camada nao for `input`, a biblioteca deve indicar configuracao invalida.
+- Se uma ativacao suportada for declarada em uma camada, a biblioteca deve inserir a camada de ativacao correspondente.
+
+### UC-02 - Treinar modelo
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Desenvolvedor JavaScript |
+| Objetivo | Ajustar os parametros da rede usando dados de entrada e alvo esperado. |
+| Pre-condicoes | Existe uma rede criada e um treinador configurado. |
+| Pos-condicoes | Os pesos da rede sao atualizados e podem melhorar a resposta ao padrao treinado. |
+
+Fluxo principal:
+
+1. O ator instancia um treinador, como `SGDTrainer`, associado a uma rede.
+2. O ator prepara um volume de entrada.
+3. O ator informa o alvo esperado, como classe ou valor de regressao.
+4. O ator chama `train`.
+5. A biblioteca executa propagacao direta, retropropagacao e atualizacao de parametros.
+6. O ator avalia a saida apos o treinamento.
+
+Fluxos alternativos:
+
+- Se parametros de treinamento forem inadequados, o treinamento pode apresentar baixa convergencia.
+- Se a rede nao estiver criada corretamente, o treinamento nao deve ser considerado valido.
+
+### UC-03 - Executar inferencia
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Desenvolvedor JavaScript |
+| Objetivo | Obter a saida da rede para uma nova entrada. |
+| Pre-condicoes | Existe uma rede criada e um volume de entrada compativel. |
+| Pos-condicoes | A biblioteca retorna um volume com probabilidades, valores ou ativacoes finais. |
+
+Fluxo principal:
+
+1. O ator cria ou obtem um `Vol` com dados de entrada.
+2. O ator chama `forward` na rede.
+3. A biblioteca propaga os dados por todas as camadas.
+4. A biblioteca retorna o volume de saida.
+5. Se a rede termina em `softmax`, o ator pode chamar `getPrediction`.
+
+Fluxos alternativos:
+
+- Se o volume de entrada nao corresponder as dimensoes esperadas, o resultado pode ser invalido ou ocorrer erro em tempo de execucao.
+- Se `getPrediction` for chamado sem camada final `softmax`, a biblioteca deve indicar uso inadequado.
+
+### UC-04 - Usar CNN com imagem
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Desenvolvedor JavaScript |
+| Objetivo | Processar imagem em uma rede convolucional. |
+| Pre-condicoes | A biblioteca esta carregada no navegador e existe uma imagem disponivel. |
+| Pos-condicoes | A imagem e transformada em volume e processada pela rede. |
+
+Fluxo principal:
+
+1. O ator define uma camada `input` com largura, altura e profundidade da imagem.
+2. O ator adiciona camadas convolucionais, pooling e camada final.
+3. O ator cria a rede com `makeLayers`.
+4. O ator converte a imagem para `Vol` usando utilitario da biblioteca.
+5. O ator chama `forward` com o volume gerado.
+6. A rede retorna a saida do processamento.
+
+Fluxos alternativos:
+
+- Se a imagem tiver dimensoes diferentes das esperadas, o ator deve redimensionar ou ajustar a configuracao da rede.
+- Se a execucao ocorrer fora do navegador, utilitarios dependentes de DOM podem nao estar disponiveis.
+
+### UC-05 - Serializar e restaurar rede
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Integrador |
+| Objetivo | Salvar e recuperar a estrutura e parametros de uma rede. |
+| Pre-condicoes | Existe uma rede criada ou um JSON valido previamente gerado. |
+| Pos-condicoes | O estado da rede e representado em JSON ou restaurado a partir dele. |
+
+Fluxo principal:
+
+1. O ator chama `toJSON` em uma rede existente.
+2. A biblioteca retorna objeto JSON com a representacao das camadas.
+3. O ator armazena ou transporta essa representacao conforme sua aplicacao externa.
+4. Para restaurar, o ator cria uma nova instancia de rede.
+5. O ator chama `fromJSON` com o objeto salvo.
+6. A biblioteca recria as camadas e parametros.
+
+Fluxos alternativos:
+
+- Se o JSON estiver incompleto ou corrompido, a restauracao pode falhar.
+- A biblioteca nao define mecanismo proprio de persistencia em banco de dados.
+
+### UC-06 - Executar demo no navegador
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Usuario de demo |
+| Objetivo | Interagir com exemplos educacionais do projeto. |
+| Pre-condicoes | O navegador consegue abrir os arquivos HTML e scripts locais da pasta `demo/`. |
+| Pos-condicoes | O usuario visualiza ou interage com uma demonstracao de redes neurais. |
+
+Fluxo principal:
+
+1. O ator abre um arquivo HTML da pasta `demo/`.
+2. O navegador carrega CSS e scripts JavaScript locais.
+3. A demo inicializa a rede ou simulacao correspondente.
+4. O ator interage com controles, dados ou visualizacoes disponiveis.
+5. A demo apresenta resultados, treinamento ou comportamento do modelo.
+
+Fluxos alternativos:
+
+- Se algum script local nao for carregado, a demo pode nao funcionar corretamente.
+- Se a demo depender de recursos especificos do navegador, ambientes antigos podem apresentar incompatibilidades.
+
+### UC-07 - Compilar biblioteca
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Mantenedor |
+| Objetivo | Gerar arquivos distribuiveis a partir dos arquivos em `src/`. |
+| Pre-condicoes | O ambiente possui Apache Ant e `yuicompressor` conforme esperado pelo script. |
+| Pos-condicoes | Os arquivos compilados e minificados sao gerados em `build/`. |
+
+Fluxo principal:
+
+1. O ator altera ou revisa arquivos em `src/`.
+2. O ator acessa a pasta `compile/`.
+3. O ator executa o comando Ant indicado no README.
+4. O script concatena os fontes.
+5. O script minifica o resultado.
+6. Os artefatos finais sao disponibilizados em `build/`.
+
+Fluxos alternativos:
+
+- Se Ant nao estiver instalado, a compilacao nao sera executada.
+- Se o compressor nao estiver disponivel, a minificacao podera falhar.
+
+### UC-08 - Rodar testes Jasmine
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Mantenedor |
+| Objetivo | Verificar comportamento basico da biblioteca apos alteracoes. |
+| Pre-condicoes | Os arquivos de teste e bibliotecas Jasmine estao disponiveis em `test/jasmine/`. |
+| Pos-condicoes | O mantenedor obtem resultado de sucesso ou falha dos testes. |
+
+Fluxo principal:
+
+1. O ator abre `test/jasmine/SpecRunner.html`.
+2. O Jasmine carrega as dependencias e especificacoes.
+3. Os testes criam uma rede neural simples.
+4. Os testes verificam inicializacao, propagacao direta, treinamento e gradiente.
+5. O runner exibe os resultados.
+
+Fluxos alternativos:
+
+- Se scripts da biblioteca nao forem carregados, os testes falham.
+- Se uma mudanca alterar comportamento esperado, o runner apresenta falhas para investigacao.
+
+### UC-09 - Experimentar Deep Q Learning
+
+| Campo | Descricao |
+| --- | --- |
+| Ator principal | Estudante/Pesquisador |
+| Objetivo | Observar aprendizado por reforco usando o modulo experimental de Deep Q Learning. |
+| Pre-condicoes | A demo de aprendizado por reforco e seus scripts estao disponiveis. |
+| Pos-condicoes | O ator observa uma simulacao ou exemplo de agente em treinamento. |
+
+Fluxo principal:
+
+1. O ator abre a demo `rldemo.html`.
+2. A pagina carrega o modulo de Deep Q Learning e scripts de apoio.
+3. A simulacao e inicializada.
+4. O ator observa o comportamento do agente ao longo do tempo.
+5. O ator usa a demo como apoio educacional ou experimental.
+
+Fluxos alternativos:
+
+- Por ser experimental, o modulo pode nao oferecer a mesma estabilidade das funcionalidades principais da biblioteca.
+- Se a demo nao carregar seus scripts, a simulacao nao sera executada.
+
+## 5. Relacionamento com Historias de Usuario
+
+| Caso de uso | Historias relacionadas |
+| --- | --- |
+| UC-01 | HU-01, HU-06 |
+| UC-02 | HU-02 |
+| UC-03 | HU-03, HU-06 |
+| UC-04 | HU-05 |
+| UC-05 | HU-04 |
+| UC-06 | HU-07, HU-12 |
+| UC-07 | HU-08 |
+| UC-08 | HU-09 |
+| UC-09 | HU-10 |
+
diff --git a/docs/contabilizacao-problemas-refatoracao.md b/docs/contabilizacao-problemas-refatoracao.md
new file mode 100644
index 00000000..da8a5206
--- /dev/null
+++ b/docs/contabilizacao-problemas-refatoracao.md
@@ -0,0 +1,150 @@
+# Contabilizacao de Problemas para Refatoracao
+
+## 1. Objetivo
+
+Este documento consolida os problemas identificados no projeto ConvNetJS por tipo, separando achados de seguranca e achados de qualidade de codigo. Ele deve servir como base quantitativa e qualitativa para priorizacao do plano de refatoracao.
+
+A contabilizacao foi derivada principalmente de:
+
+- `docs/plano-de-refatoracao.md`
+- `docs/relatorio-vulnerabilidades-code-smells.md`
+- `docs/documento-de-requisitos-de-software.md`
+- `docs/historias-de-usuario.md`
+- `docs/casos-de-uso.md`
+- inspecao estatica dos diretorios `src/`, `demo/`, `test/`, `compile/`, `build/` e `.github/`
+
+## 2. Resumo Geral
+
+| Tipo de problema | Quantidade de categorias | Ocorrencias contabilizadas | Severidade predominante | Prioridade de tratamento |
+| --- | ---: | ---: | --- | --- |
+| Seguranca | 7 | 103 | Media | Alta |
+| Qualidade | 7 | 2.085 | Media | Alta |
+| Total | 14 | 2.188 | Media | Alta |
+
+Observacao: as quantidades representam ocorrencias encontradas por busca estatica textual. Algumas ocorrencias aparecem em dependencias empacotadas, demos ou arquivos de teste, portanto devem ser tratadas conforme contexto antes de qualquer correcao automatica.
+
+## 3. Problemas de Seguranca
+
+| ID | Tipo | Quantidade | Severidade | Area principal | Prioridade | Acao esperada no plano de refatoracao |
+| --- | --- | ---: | --- | --- | --- | --- |
+| SEG-01 | Execucao dinamica de codigo com `eval()` | 12 | Alta | `demo/`, `test/` | Alta | Substituir por configuracao estruturada, isolar demos ou documentar sandbox. |
+| SEG-02 | Manipulacao dinamica de HTML | 32 | Media | `demo/` | Media | Trocar por `textContent`/DOM seguro ou sanitizar HTML dinamico. |
+| SEG-03 | Links e recursos HTTP sem TLS | 40 | Media | README, demos, testes | Media | Migrar para HTTPS quando possivel e evitar recursos remotos inseguros. |
+| SEG-04 | Dependencia legada jQuery 1.8.3 | 8 referencias | Alta | `demo/` | Alta | Atualizar/remover jQuery ou restringir demos a uso local. |
+| SEG-05 | Dependencia legada Jasmine 2.0.0 | 5 referencias | Media | `test/` | Baixa | Planejar atualizacao do runner de testes. |
+| SEG-06 | Build com YUI Compressor 2.4.8 | 2 referencias | Media | `compile/` | Media | Documentar origem/hash e avaliar substituto moderno. |
+| SEG-07 | Envio opcional de SARIF para servico externo | 4 | Baixa | `.github/` | Baixa | Documentar comportamento e permitir controle explicito por variavel. |
+
+### 3.1 Total por Severidade - Seguranca
+
+| Severidade | Quantidade de categorias | Ocorrencias |
+| --- | ---: | ---: |
+| Alta | 2 | 20 |
+| Media | 4 | 79 |
+| Baixa | 1 | 4 |
+
+### 3.2 Interpretacao
+
+Os riscos de seguranca estao concentrados nas demos e no ferramental legado. O nucleo da biblioteca em `src/` nao apresenta, por esta triagem, o mesmo nivel de exposicao direta que as paginas demonstrativas. Ainda assim, como as demos sao parte do escopo educacional do projeto, elas devem ser tratadas no plano de refatoracao.
+
+Prioridades de seguranca:
+
+1. Reduzir ou isolar o uso de `eval()` nas demos.
+2. Atualizar ou remover jQuery 1.8.3.
+3. Revisar manipulacao dinamica de HTML.
+4. Migrar links e recursos HTTP para HTTPS.
+5. Modernizar ou documentar melhor ferramentas legadas de teste e build.
+
+## 4. Problemas de Qualidade
+
+| ID | Tipo | Quantidade | Severidade | Area principal | Prioridade | Acao esperada no plano de refatoracao |
+| --- | --- | ---: | --- | --- | --- | --- |
+| QUA-01 | Uso extensivo de `var` | 1.610 | Media | `src/`, `demo/`, `test/` | Media | Migrar gradualmente para `let`/`const` com testes de regressao. |
+| QUA-02 | Comparacoes nao estritas | 293 | Media | `src/`, `demo/`, `test/` | Media | Migrar para `===`/`!==` onde preservar comportamento. |
+| QUA-03 | Acoplamento ao namespace global | 110 | Media | `src/`, `build/` | Alta | Mapear API publica e criar organizacao interna menos acoplada. |
+| QUA-04 | Aleatoriedade nao controlada | 34 | Media | `src/`, `demo/`, `test/`, `build/` | Alta | Criar mecanismo de aleatoriedade controlavel para testes. |
+| QUA-05 | Logs diretos no codigo | 17 | Baixa | `src/`, `demo/`, `test/`, `.github/` | Baixa | Padronizar warnings, erros e logs de demo. |
+| QUA-06 | Comentarios TODO/FIXME | 14 | Baixa | `src/`, `demo/`, `test/` | Baixa | Converter TODOs do codigo proprio em backlog rastreavel. |
+| QUA-07 | Build e testes legados | 7 referencias criticas | Media | `compile/`, `test/`, exports | Alta | Preservar compatibilidade enquanto se moderniza build/testes. |
+
+### 4.1 Total por Severidade - Qualidade
+
+| Severidade | Quantidade de categorias | Ocorrencias |
+| --- | ---: | ---: |
+| Alta | 0 | 0 |
+| Media | 5 | 2.054 |
+| Baixa | 2 | 31 |
+
+### 4.2 Interpretacao
+
+Os problemas de qualidade sao numericamente maiores que os de seguranca porque o projeto possui estilo JavaScript historico, API baseada em namespace global e processo de build por concatenacao. Nem todos devem ser corrigidos de uma vez: o risco de quebrar a API publica e alto, principalmente porque os requisitos exigem compatibilidade com navegador, Node.js, demos e bundle em `build/`.
+
+Prioridades de qualidade:
+
+1. Mapear e proteger a API publica antes de refatorar.
+2. Ampliar testes de regressao para `Net`, `Vol`, `Trainer`, camadas e serializacao.
+3. Reduzir acoplamento interno em `Net.makeLayers` e `fromJSON`.
+4. Controlar aleatoriedade para testes deterministas.
+5. Modernizar `var` e comparacoes nao estritas gradualmente.
+
+## 5. Matriz de Priorizacao para Refatoracao
+
+| Prioridade | Problemas relacionados | Justificativa | Fase sugerida |
+| --- | --- | --- | --- |
+| P1 | SEG-01, SEG-04, QUA-03, QUA-04, QUA-07 | Alto risco de seguranca ou risco estrutural para evolucao segura. | Fases 0, 1, 3, 4, 5 |
+| P2 | SEG-02, SEG-03, SEG-06, QUA-01, QUA-02 | Melhorias importantes, mas que exigem testes para evitar regressao. | Fases 1, 2, 5, 6 |
+| P3 | SEG-05, SEG-07, QUA-05, QUA-06 | Baixo impacto imediato ou restrito a teste/pipeline/documentacao. | Fases 5, 6 |
+
+## 6. Relacao com o Plano de Refatoracao
+
+| Fase do plano | Problemas contemplados | Resultado esperado |
+| --- | --- | --- |
+| Fase 0 - Baseline e Inventario | QUA-03, QUA-07 | API publica e demos criticas mapeadas antes de mudancas. |
+| Fase 1 - Fortalecimento de Testes | QUA-04, QUA-07, SEG-05 | Rede de seguranca para refatorar codigo legado. |
+| Fase 2 - Validacoes e Tratamento de Erros | QUA-05, QUA-06 | Falhas mais previsiveis e menor dependencia de logs soltos. |
+| Fase 3 - Separacao Interna de Responsabilidades | QUA-03, QUA-01, QUA-02 | Menor acoplamento e codigo mais legivel. |
+| Fase 4 - Refatoracao de Treinadores e Aleatoriedade | QUA-04 | Treinamento e testes mais reproduziveis. |
+| Fase 5 - Build, Distribuicao e Compatibilidade | SEG-05, SEG-06, SEG-07, QUA-07 | Build/testes mais auditaveis e compativeis. |
+| Fase 6 - Demos e Documentacao Tecnica | SEG-01, SEG-02, SEG-03, SEG-04 | Demos mais seguras e documentadas. |
+
+## 7. Relacao com Casos de Uso
+
+| Caso de uso | Problemas mais relevantes | Impacto |
+| --- | --- | --- |
+| UC-01 - Definir rede neural | QUA-03, QUA-05, QUA-07 | Afeta manutencao de `makeLayers` e validacoes. |
+| UC-02 - Treinar modelo | QUA-04, QUA-05 | Afeta reprodutibilidade e diagnostico de treinamento. |
+| UC-03 - Executar inferencia | QUA-03, QUA-07 | Exige preservacao da API publica durante refatoracao. |
+| UC-04 - Usar CNN com imagem | SEG-02, QUA-04 | Afeta demos de imagem e manipulacao dinamica de DOM. |
+| UC-05 - Serializar e restaurar rede | QUA-03, QUA-07 | Requer testes para nao quebrar JSON de modelos. |
+| UC-06 - Executar demo no navegador | SEG-01, SEG-02, SEG-03, SEG-04 | Principal area de risco de seguranca. |
+| UC-07 - Compilar biblioteca | SEG-06, QUA-07 | Build legado precisa de controle e documentacao. |
+| UC-08 - Rodar testes Jasmine | SEG-05, QUA-07 | Testes precisam ser preservados e depois modernizados. |
+| UC-09 - Experimentar Deep Q Learning | SEG-01, QUA-04 | Demo experimental usa execucao dinamica e aleatoriedade. |
+
+## 8. Indicadores para Acompanhar a Refatoracao
+
+| Indicador | Valor inicial | Meta sugerida |
+| --- | ---: | --- |
+| Ocorrencias de `eval()` | 12 | 0 em demos publicaveis ou uso isolado/documentado |
+| Referencias a jQuery 1.8.3 | 8 | 0 ou dependencia atualizada |
+| Ocorrencias de HTML dinamico inseguro | 32 | Reduzir ou sanitizar pontos com entrada variavel |
+| Links HTTP | 40 | Migrar para HTTPS quando disponivel |
+| Ocorrencias de `var` | 1.610 | Reducao gradual por modulo refatorado |
+| Comparacoes nao estritas | 293 | Reducao gradual com testes |
+| Usos de `Math.random` | 34 | Centralizar aleatoriedade no nucleo e testes |
+| Logs diretos | 17 | Manter apenas logs intencionais de demo/pipeline |
+| TODO/FIXME | 14 | Converter TODOs proprios em backlog |
+
+## 9. Conclusao
+
+A base de refatoracao deve priorizar seguranca nas demos e qualidade estrutural no nucleo da biblioteca. Embora os problemas de qualidade sejam mais numerosos, os itens de seguranca com `eval()` e jQuery legado merecem tratamento prioritario quando as demos forem publicadas ou usadas fora de ambiente local.
+
+Para reduzir risco de regressao, a ordem recomendada e:
+
+1. inventariar API publica e demos criticas;
+2. ampliar testes;
+3. corrigir ou isolar riscos de seguranca em demos;
+4. reduzir acoplamento interno;
+5. controlar aleatoriedade;
+6. modernizar build e estilo de codigo gradualmente.
+
diff --git a/docs/diagramas-fluxos-classes.md b/docs/diagramas-fluxos-classes.md
new file mode 100644
index 00000000..b04d482f
--- /dev/null
+++ b/docs/diagramas-fluxos-classes.md
@@ -0,0 +1,419 @@
+# Diagramas de Fluxos e Classes
+
+## 1. Visao Geral
+
+Este documento apresenta diagramas baseados no Documento de Requisitos de Software, Historias de Usuario e Casos de Uso do ConvNetJS.
+
+Os diagramas usam sintaxe Mermaid para facilitar visualizacao em ferramentas compativeis com Markdown.
+
+## 2. Diagrama Geral de Casos de Uso
+
+```mermaid
+flowchart LR
+  Dev[Desenvolvedor JavaScript]
+  Est[Estudante/Pesquisador]
+  DemoUser[Usuario de demo]
+  Mant[Mantenedor]
+  Int[Integrador]
+
+  UC01[UC-01 Definir rede neural]
+  UC02[UC-02 Treinar modelo]
+  UC03[UC-03 Executar inferencia]
+  UC04[UC-04 Usar CNN com imagem]
+  UC05[UC-05 Serializar e restaurar rede]
+  UC06[UC-06 Executar demo no navegador]
+  UC07[UC-07 Compilar biblioteca]
+  UC08[UC-08 Rodar testes Jasmine]
+  UC09[UC-09 Experimentar Deep Q Learning]
+
+  Dev --> UC01
+  Dev --> UC02
+  Dev --> UC03
+  Dev --> UC04
+  Int --> UC05
+  Int --> UC03
+  DemoUser --> UC06
+  Mant --> UC07
+  Mant --> UC08
+  Est --> UC06
+  Est --> UC09
+
+  UC01 --> UC02
+  UC01 --> UC03
+  UC04 --> UC03
+  UC02 --> UC05
+  UC05 --> UC03
+```
+
+## 3. Fluxo UC-01 - Definir Rede Neural
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Instanciar convnetjs.Net]
+  B --> C[Criar lista layer_defs]
+  C --> D{Primeira camada e input?}
+  D -- Nao --> E[Indicar configuracao invalida]
+  E --> Z[Fim]
+  D -- Sim --> F[Adicionar camadas intermediarias]
+  F --> G[Adicionar camada final softmax, svm ou regression]
+  G --> H[Chamar net.makeLayers layer_defs]
+  H --> I{Camadas reconhecidas?}
+  I -- Nao --> J[Indicar tipo de camada invalido]
+  J --> Z
+  I -- Sim --> K[Calcular dimensoes e montar sequencia interna]
+  K --> L[Rede pronta para treino ou inferencia]
+  L --> Z
+```
+
+## 4. Fluxo UC-02 - Treinar Modelo
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Receber rede criada]
+  B --> C[Configurar Trainer ou SGDTrainer]
+  C --> D[Preparar Vol de entrada]
+  D --> E[Informar alvo esperado]
+  E --> F[Executar trainer.train x y]
+  F --> G[Executar forward em modo treinamento]
+  G --> H[Executar backward e calcular gradientes]
+  H --> I{Batch completo?}
+  I -- Nao --> J[Acumular gradientes]
+  J --> M[Retornar metricas de treino]
+  I -- Sim --> K[Aplicar otimizador nos parametros]
+  K --> L[Zerar gradientes acumulados]
+  L --> M
+  M --> N[Modelo atualizado]
+  N --> O[Fim]
+```
+
+## 5. Fluxo UC-03 - Executar Inferencia
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Receber rede criada]
+  B --> C[Receber Vol de entrada]
+  C --> D[Chamar net.forward x]
+  D --> E[Propagar entrada pela camada input]
+  E --> F[Propagar pelas camadas intermediarias]
+  F --> G[Propagar pela camada final]
+  G --> H[Retornar Vol de saida]
+  H --> I{Ultima camada e softmax?}
+  I -- Sim --> J[Permitir getPrediction]
+  I -- Nao --> K[Usar valores brutos da saida]
+  J --> L[Retornar classe de maior probabilidade]
+  K --> M[Retornar valores de regressao ou ativacao]
+  L --> N[Fim]
+  M --> N
+```
+
+## 6. Fluxo UC-04 - Usar CNN com Imagem
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Carregar biblioteca no navegador]
+  B --> C[Obter elemento de imagem]
+  C --> D[Definir input com largura, altura e profundidade]
+  D --> E[Adicionar camadas conv e pool]
+  E --> F[Adicionar camada final]
+  F --> G[Criar rede com makeLayers]
+  G --> H[Converter imagem com img_to_vol]
+  H --> I{Dimensoes compativeis?}
+  I -- Nao --> J[Ajustar imagem ou configuracao da rede]
+  J --> H
+  I -- Sim --> K[Executar forward]
+  K --> L[Obter saida da CNN]
+  L --> M[Fim]
+```
+
+## 7. Fluxo UC-05 - Serializar e Restaurar Rede
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B{Operacao desejada}
+  B -- Serializar --> C[Receber rede existente]
+  C --> D[Chamar net.toJSON]
+  D --> E[Gerar JSON com camadas e parametros]
+  E --> F[Aplicacao externa armazena JSON]
+  F --> Z[Fim]
+
+  B -- Restaurar --> G[Receber JSON salvo]
+  G --> H{JSON possui camadas validas?}
+  H -- Nao --> I[Indicar restauracao invalida]
+  I --> Z
+  H -- Sim --> J[Criar nova instancia de Net]
+  J --> K[Chamar net.fromJSON]
+  K --> L[Recriar camadas e parametros]
+  L --> M[Rede pronta para inferencia ou treino]
+  M --> Z
+```
+
+## 8. Fluxo UC-06 - Executar Demo no Navegador
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Usuario abre HTML em demo]
+  B --> C[Navegador carrega CSS e scripts locais]
+  C --> D{Scripts carregados com sucesso?}
+  D -- Nao --> E[Demo nao inicializa corretamente]
+  E --> Z[Fim]
+  D -- Sim --> F[Inicializar rede, dados ou simulacao]
+  F --> G[Usuario interage com controles da demo]
+  G --> H[Executar treinamento, inferencia ou visualizacao]
+  H --> I[Atualizar canvas, texto ou graficos]
+  I --> Z
+```
+
+## 9. Fluxo UC-07 - Compilar Biblioteca
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Mantenedor altera ou revisa src]
+  B --> C[Acessar pasta compile]
+  C --> D[Executar build Ant]
+  D --> E{Ant e YUI Compressor disponiveis?}
+  E -- Nao --> F[Build falha por ambiente incompleto]
+  F --> Z[Fim]
+  E -- Sim --> G[Concatenar arquivos src em ordem fixa]
+  G --> H[Gerar build/convnet.js]
+  H --> I[Minificar arquivo gerado]
+  I --> J[Gerar build/convnet-min.js]
+  J --> K[Validar artefatos de distribuicao]
+  K --> Z
+```
+
+## 10. Fluxo UC-08 - Rodar Testes Jasmine
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Abrir test/jasmine/SpecRunner.html]
+  B --> C[Carregar Jasmine]
+  C --> D[Carregar biblioteca ConvNetJS]
+  D --> E[Carregar specs]
+  E --> F[Executar testes de inicializacao]
+  F --> G[Executar testes de forward]
+  G --> H[Executar testes de treinamento]
+  H --> I[Executar teste de gradiente]
+  I --> J{Todos passaram?}
+  J -- Sim --> K[Resultado aprovado]
+  J -- Nao --> L[Exibir falhas para investigacao]
+  K --> Z[Fim]
+  L --> Z
+```
+
+## 11. Fluxo UC-09 - Experimentar Deep Q Learning
+
+```mermaid
+flowchart TD
+  A[Inicio] --> B[Abrir demo rldemo.html]
+  B --> C[Carregar convnetjs e deepqlearn]
+  C --> D[Inicializar ambiente da simulacao]
+  D --> E[Inicializar agente e Brain]
+  E --> F[Capturar estado do ambiente]
+  F --> G[Brain escolhe acao]
+  G --> H[Ambiente aplica acao]
+  H --> I[Calcular recompensa]
+  I --> J[Brain aprende com recompensa]
+  J --> K{Continuar simulacao?}
+  K -- Sim --> F
+  K -- Nao --> L[Fim]
+```
+
+## 12. Diagrama de Classes Conceitual
+
+```mermaid
+classDiagram
+  class convnetjs {
+    +REVISION
+    +Net
+    +Vol
+    +Trainer
+    +SGDTrainer
+    +MagicNet
+    +img_to_vol()
+    +augment()
+  }
+
+  class Net {
+    +layers
+    +makeLayers(defs)
+    +forward(V, is_training)
+    +backward(y)
+    +getCostLoss(V, y)
+    +getParamsAndGrads()
+    +getPrediction()
+    +toJSON()
+    +fromJSON(json)
+  }
+
+  class Vol {
+    +sx
+    +sy
+    +depth
+    +w
+    +dw
+    +get(x, y, d)
+    +set(x, y, d, v)
+    +add(x, y, d, v)
+    +get_grad(x, y, d)
+    +set_grad(x, y, d, v)
+    +add_grad(x, y, d, v)
+    +cloneAndZero()
+    +clone()
+    +addFrom(V)
+    +addFromScaled(V, a)
+    +setConst(a)
+    +toJSON()
+    +fromJSON(json)
+  }
+
+  class Trainer {
+    +net
+    +learning_rate
+    +l1_decay
+    +l2_decay
+    +batch_size
+    +method
+    +momentum
+    +train(x, y)
+  }
+
+  class Layer {
+    <<interface>>
+    +layer_type
+    +out_sx
+    +out_sy
+    +out_depth
+    +forward(V, is_training)
+    +backward(y)
+    +getParamsAndGrads()
+    +toJSON()
+    +fromJSON(json)
+  }
+
+  class InputLayer
+  class FullyConnLayer
+  class ConvLayer
+  class PoolLayer
+  class DropoutLayer
+  class LocalResponseNormalizationLayer
+  class ReluLayer
+  class SigmoidLayer
+  class TanhLayer
+  class MaxoutLayer
+  class SoftmaxLayer
+  class SVMLayer
+  class RegressionLayer
+  class MagicNet
+  class Brain
+
+  convnetjs o-- Net
+  convnetjs o-- Vol
+  convnetjs o-- Trainer
+  convnetjs o-- MagicNet
+
+  Net "1" o-- "*" Layer
+  Trainer --> Net
+  Net --> Vol
+  Layer --> Vol
+
+  Layer <|.. InputLayer
+  Layer <|.. FullyConnLayer
+  Layer <|.. ConvLayer
+  Layer <|.. PoolLayer
+  Layer <|.. DropoutLayer
+  Layer <|.. LocalResponseNormalizationLayer
+  Layer <|.. ReluLayer
+  Layer <|.. SigmoidLayer
+  Layer <|.. TanhLayer
+  Layer <|.. MaxoutLayer
+  Layer <|.. SoftmaxLayer
+  Layer <|.. SVMLayer
+  Layer <|.. RegressionLayer
+
+  FullyConnLayer o-- Vol : filters/biases
+  ConvLayer o-- Vol : filters/biases
+  MagicNet --> Net
+  MagicNet --> Trainer
+  Brain --> Net : value_net
+  Brain --> Trainer : tdtrainer
+```
+
+## 13. Diagrama de Componentes
+
+```mermaid
+flowchart TB
+  subgraph SRC[src]
+    Init[convnet_init.js]
+    Util[convnet_util.js]
+    Vol[convnet_vol.js e convnet_vol_util.js]
+    Layers[convnet_layers_*]
+    Net[convnet_net.js]
+    Trainers[convnet_trainers.js]
+    Magic[convnet_magicnet.js]
+    Export[convnet_export.js]
+  end
+
+  subgraph BUILD[build]
+    Bundle[convnet.js]
+    Min[convnet-min.js]
+    RL[deepqlearn.js]
+    Vis[vis.js]
+    BuildUtil[util.js]
+  end
+
+  subgraph DEMO[demo]
+    Html[Demos HTML]
+    DemoJS[Scripts JS das demos]
+    CSS[CSS]
+  end
+
+  subgraph TEST[test]
+    Jasmine[Jasmine 2.0.0]
+    Specs[NeuralNetSpec.js]
+    Runner[SpecRunner.html]
+  end
+
+  subgraph COMPILE[compile]
+    Ant[build.xml]
+    YUI[yuicompressor-2.4.8.jar]
+  end
+
+  Init --> Util
+  Util --> Vol
+  Vol --> Layers
+  Layers --> Net
+  Net --> Trainers
+  Trainers --> Magic
+  Magic --> Export
+
+  Ant --> Bundle
+  YUI --> Min
+  SRC --> Ant
+  Bundle --> Html
+  Bundle --> Specs
+  RL --> Html
+  Vis --> Html
+  BuildUtil --> Html
+  DemoJS --> Html
+  CSS --> Html
+  Jasmine --> Runner
+  Specs --> Runner
+```
+
+## 14. Rastreabilidade dos Diagramas
+
+| Diagrama | Base documental | Requisitos/casos relacionados |
+| --- | --- | --- |
+| Diagrama geral de casos de uso | Casos de Uso e Historias de Usuario | UC-01 a UC-09, HU-01 a HU-12 |
+| Fluxo de definicao de rede | Documento de Requisitos e UC-01 | RF-01, RF-02, RF-03 a RF-08 |
+| Fluxo de treinamento | UC-02 | RF-10, RF-11 |
+| Fluxo de inferencia | UC-03 | RF-09, RF-12, RF-14 |
+| Fluxo de CNN com imagem | UC-04 | RF-04, RF-05, RF-15 |
+| Fluxo de serializacao | UC-05 | RF-13 |
+| Fluxo de demo | UC-06 | RF-18, RNF-05 |
+| Fluxo de build | UC-07 | RF-19, RNF-04 |
+| Fluxo de testes | UC-08 | RF-20, RNF-07 |
+| Fluxo de Deep Q Learning | UC-09 | RF-21 |
+| Diagrama de classes | Requisitos, README e `src/` | RF-01 a RF-17 |
+| Diagrama de componentes | Plano de Refatoracao e estrutura do repositorio | RF-16 a RF-20 |
+
diff --git a/docs/documento-de-requisitos-de-software.md b/docs/documento-de-requisitos-de-software.md
new file mode 100644
index 00000000..a0ddff46
--- /dev/null
+++ b/docs/documento-de-requisitos-de-software.md
@@ -0,0 +1,151 @@
+# Documento de Requisitos de Software
+
+## 1. Identificacao do Projeto
+
+| Campo | Descricao |
+| --- | --- |
+| Projeto | ConvNetJS |
+| Tipo de software | Biblioteca JavaScript para redes neurais e redes convolucionais |
+| Linguagem principal | JavaScript |
+| Ambientes de execucao | Navegador e Node.js |
+| Artefato principal | `build/convnet.js` |
+| Fonte principal de requisitos | `sobre este projeto.md`, `Readme.md`, `src/`, `demo/` e `test/jasmine/` |
+
+## 2. Visao Geral
+
+ConvNetJS e uma biblioteca JavaScript para criacao, treinamento e execucao de redes neurais, com suporte a redes totalmente conectadas, redes convolucionais, funcoes de perda, otimizadores e demos educacionais executadas no navegador.
+
+O projeto nao e uma aplicacao web com backend, banco de dados, autenticacao ou area administrativa. Seu objetivo principal e oferecer um motor de Deep Learning em JavaScript, utilizavel por desenvolvedores, estudantes e pesquisadores em contextos educacionais, experimentais e de prototipacao.
+
+## 3. Proposito
+
+Este documento registra os requisitos de software levantados a partir do estado atual do repositorio. Ele serve como referencia para entendimento do escopo, validacao das funcionalidades existentes, manutencao futura e comunicacao entre pessoas tecnicas e nao tecnicas envolvidas no projeto.
+
+## 4. Escopo
+
+### 4.1 Dentro do escopo
+
+- Criacao de redes neurais por definicoes de camadas.
+- Execucao de propagacao direta para inferencia.
+- Treinamento por retropropagacao usando treinadores disponiveis.
+- Suporte a camadas densas, convolucionais, pooling, dropout, normalizacao e ativacoes.
+- Suporte a tarefas de classificacao, regressao e modulo experimental de aprendizado por reforco.
+- Serializacao e restauracao de redes via JSON.
+- Uso em navegador e Node.js/CommonJS.
+- Demos estaticas para aprendizado e experimentacao.
+- Testes de comportamento basico com Jasmine.
+
+### 4.2 Fora do escopo
+
+- Cadastro, login, controle de acesso ou gestao de usuarios.
+- Banco de dados, tabelas, migracoes ou persistencia em servidor.
+- Backend proprio, APIs REST ou integracoes externas obrigatorias.
+- Treinamento distribuido, uso de GPU ou execucao de alto desempenho em producao.
+- Interface administrativa, dashboard SaaS ou produto hospedado.
+
+## 5. Publico-Alvo
+
+| Perfil | Interesse principal |
+| --- | --- |
+| Desenvolvedor JavaScript | Integrar a biblioteca em projetos browser ou Node.js |
+| Estudante/Pesquisador | Aprender e experimentar conceitos de redes neurais |
+| Usuario de demo | Visualizar exemplos interativos no navegador |
+| Mantenedor | Corrigir, testar, compilar e distribuir a biblioteca |
+| Integrador | Usar o bundle compilado ou a API CommonJS em outro sistema |
+
+## 6. Visao do Produto
+
+O ConvNetJS disponibiliza uma API programatica baseada em objetos como `Net`, `Vol` e `SGDTrainer`. O usuario define uma lista de camadas, cria a rede, executa inferencia com `forward`, treina a rede com um treinador e pode salvar ou restaurar o estado por JSON.
+
+A biblioteca tambem inclui demos HTML/JS que demonstram classificacao, regressao, autoencoder, CNN para imagens, comparacao de otimizadores e aprendizado por reforco com Deep Q Learning.
+
+## 7. Requisitos Funcionais
+
+| ID | Requisito | Prioridade | Origem |
+| --- | --- | --- | --- |
+| RF-01 | O sistema deve permitir definir redes neurais a partir de uma lista ordenada de camadas. | Alta | `src/convnet_net.js` |
+| RF-02 | O sistema deve validar que a primeira camada da rede seja uma camada de entrada. | Alta | `src/convnet_net.js` |
+| RF-03 | O sistema deve suportar camadas totalmente conectadas para processamento neural denso. | Alta | `src/convnet_layers_dotproducts.js` |
+| RF-04 | O sistema deve suportar camadas convolucionais para processamento de dados de imagem ou volumes. | Alta | `src/convnet_layers_dotproducts.js` |
+| RF-05 | O sistema deve suportar camadas de pooling para reducao espacial de volumes. | Alta | `src/convnet_layers_pool.js` |
+| RF-06 | O sistema deve suportar funcoes de ativacao como ReLU, sigmoid, tanh e maxout. | Alta | `src/convnet_layers_nonlinearities.js` |
+| RF-07 | O sistema deve suportar dropout e normalizacao local quando configurados na rede. | Media | `src/convnet_layers_dropout.js`, `src/convnet_layers_normalization.js` |
+| RF-08 | O sistema deve suportar funcoes de perda para classificacao e regressao, incluindo softmax, SVM e L2. | Alta | `src/convnet_layers_loss.js` |
+| RF-09 | O sistema deve executar propagacao direta e retornar um volume de saida. | Alta | `src/convnet_net.js` |
+| RF-10 | O sistema deve executar retropropagacao para calculo de perdas e gradientes. | Alta | `src/convnet_net.js` |
+| RF-11 | O sistema deve fornecer treinadores/otimizadores para ajuste dos parametros da rede. | Alta | `src/convnet_trainers.js` |
+| RF-12 | O sistema deve permitir obter a predicao de maior probabilidade em redes com softmax. | Media | `src/convnet_net.js` |
+| RF-13 | O sistema deve permitir serializar e restaurar redes por JSON. | Alta | `src/convnet_net.js` |
+| RF-14 | O sistema deve fornecer estruturas de volume para armazenar dados, pesos e gradientes. | Alta | `src/convnet_vol.js` |
+| RF-15 | O sistema deve disponibilizar utilitario para converter imagem em volume quando usado no navegador. | Media | `Readme.md`, `src/convnet_vol_util.js` |
+| RF-16 | O sistema deve expor a biblioteca como objeto global no navegador. | Alta | `src/convnet_export.js` |
+| RF-17 | O sistema deve exportar a biblioteca via CommonJS quando executado em Node.js. | Alta | `src/convnet_export.js` |
+| RF-18 | O sistema deve disponibilizar demos estaticas para exemplos de classificacao, regressao, CNN, autoencoder, treinamento e aprendizado por reforco. | Media | `demo/`, `Readme.md` |
+| RF-19 | O sistema deve disponibilizar script de compilacao para gerar versoes concatenada e minificada da biblioteca. | Media | `compile/build.xml` |
+| RF-20 | O sistema deve conter testes automatizados basicos para verificar inicializacao, inferencia, treinamento e gradientes. | Media | `test/jasmine/spec/NeuralNetSpec.js` |
+| RF-21 | O sistema deve disponibilizar modulo experimental de Deep Q Learning. | Baixa | `build/deepqlearn.js`, `demo/rldemo.html` |
+
+## 8. Requisitos Nao Funcionais
+
+| ID | Requisito | Prioridade | Categoria |
+| --- | --- | --- | --- |
+| RNF-01 | A biblioteca deve ser executavel em navegadores por meio de arquivos JavaScript estaticos. | Alta | Portabilidade |
+| RNF-02 | A biblioteca deve manter compatibilidade com uso em Node.js/CommonJS conforme exportacao existente. | Alta | Compatibilidade |
+| RNF-03 | O codigo-fonte deve permanecer modular em `src/`, separado por responsabilidade de camadas, volumes, rede, treinadores e utilitarios. | Media | Manutenibilidade |
+| RNF-04 | A distribuicao deve oferecer arquivo compilado e arquivo minificado em `build/`. | Media | Distribuicao |
+| RNF-05 | As demos devem funcionar sem backend proprio, usando HTML, CSS e JavaScript estaticos. | Alta | Implantacao |
+| RNF-06 | A biblioteca deve evitar dependencia obrigatoria de APIs externas para seu funcionamento principal. | Alta | Independencia |
+| RNF-07 | Os testes devem ser executaveis no navegador por meio do runner Jasmine existente. | Media | Testabilidade |
+| RNF-08 | A API deve permitir exemplos curtos e compreensiveis para fins educacionais. | Media | Usabilidade |
+| RNF-09 | A execucao deve ser adequada a experimentos pequenos e medios em JavaScript, sem promessa de desempenho de producao com GPU. | Media | Desempenho |
+| RNF-10 | O projeto deve respeitar a licenca MIT presente no repositorio. | Alta | Legal |
+| RNF-11 | O uso das demos deve ser restrito ao processamento local no navegador, sem envio obrigatorio de dados a servidor. | Media | Privacidade |
+| RNF-12 | O projeto deve preservar o aviso de manutencao limitada indicado no README. | Media | Governanca |
+
+## 9. Regras de Negocio e Restricoes
+
+| ID | Regra/Restricao | Descricao |
+| --- | --- | --- |
+| REG-01 | Camada inicial obrigatoria | Toda rede criada pela API deve iniciar com uma camada do tipo `input`. |
+| REG-02 | Rede minima | Uma rede deve possuir ao menos uma camada de entrada e uma camada final de perda ou saida adequada. |
+| REG-03 | Saida softmax | A funcao de predicao por maior probabilidade pressupoe que a ultima camada seja `softmax`. |
+| REG-04 | Demos estaticas | As demonstracoes devem ser tratadas como paginas estaticas de exemplo, nao como aplicacao web completa. |
+| REG-05 | Sem persistencia em servidor | Persistencia, quando necessaria, deve ocorrer por mecanismos locais como serializacao JSON, nao por banco de dados do projeto. |
+| REG-06 | Modulo experimental | O modulo de Deep Q Learning deve ser documentado como experimental. |
+
+## 10. Interfaces Externas
+
+| Interface | Descricao |
+| --- | --- |
+| Browser global | Exposicao da biblioteca como `window.convnetjs`. |
+| CommonJS | Exportacao via `module.exports` para uso com `require`. |
+| Arquivos HTML de demo | Paginas em `demo/` que consomem scripts locais e a biblioteca compilada. |
+| Jasmine SpecRunner | Runner HTML para execucao dos testes automatizados existentes. |
+| Build Ant | Script `compile/build.xml` para concatenacao e minificacao. |
+
+## 11. Premissas
+
+- O levantamento descreve o software existente, nao uma nova versao do produto.
+- O projeto e usado principalmente para estudo, prototipacao e demonstracao.
+- Nao ha banco de dados, backend, autenticacao ou integracao externa obrigatoria.
+- A manutencao do projeto e historicamente limitada, conforme aviso do README.
+- Os requisitos foram derivados por analise documental e inspecao do repositorio.
+
+## 12. Matriz de Rastreabilidade
+
+| Requisito | Historias relacionadas | Casos de uso relacionados |
+| --- | --- | --- |
+| RF-01, RF-02 | HU-01 | UC-01 |
+| RF-03, RF-04, RF-05, RF-06, RF-07, RF-08 | HU-01, HU-02 | UC-01, UC-04 |
+| RF-09, RF-12 | HU-03 | UC-03 |
+| RF-10, RF-11 | HU-02 | UC-02 |
+| RF-13 | HU-04 | UC-05 |
+| RF-14, RF-15 | HU-03, HU-05 | UC-03, UC-04 |
+| RF-16, RF-17 | HU-06 | UC-01, UC-03 |
+| RF-18 | HU-05, HU-07 | UC-06 |
+| RF-19 | HU-08 | UC-07 |
+| RF-20 | HU-09 | UC-08 |
+| RF-21 | HU-10 | UC-09 |
+| RNF-01, RNF-02, RNF-05, RNF-06 | HU-06, HU-07 | UC-06 |
+| RNF-03, RNF-04, RNF-07 | HU-08, HU-09 | UC-07, UC-08 |
+
diff --git a/docs/historias-de-usuario.md b/docs/historias-de-usuario.md
new file mode 100644
index 00000000..4c3636e5
--- /dev/null
+++ b/docs/historias-de-usuario.md
@@ -0,0 +1,103 @@
+# Historias de Usuario
+
+## 1. Visao Geral
+
+Este documento apresenta historias de usuario para o ConvNetJS, considerando o projeto como uma biblioteca JavaScript de redes neurais com demos estaticas no navegador e suporte a uso em Node.js.
+
+As historias seguem o formato:
+
+> Como [ator], quero [acao], para [beneficio].
+
+## 2. Atores
+
+| Ator | Descricao |
+| --- | --- |
+| Desenvolvedor JavaScript | Pessoa que integra ou usa a biblioteca em projetos browser ou Node.js. |
+| Estudante/Pesquisador | Pessoa que aprende, testa ou demonstra conceitos de Deep Learning. |
+| Usuario de demo | Pessoa que interage com exemplos prontos no navegador. |
+| Mantenedor | Pessoa que corrige, testa, compila e distribui a biblioteca. |
+| Integrador | Pessoa que usa o bundle compilado ou a API CommonJS em outro sistema. |
+
+## 3. Historias
+
+| ID | Historia | Prioridade | Requisitos relacionados |
+| --- | --- | --- | --- |
+| HU-01 | Como desenvolvedor JavaScript, quero definir uma rede neural por uma lista de camadas, para configurar arquiteturas adequadas ao meu problema. | Alta | RF-01, RF-02, RF-03, RF-04, RF-05, RF-06, RF-07, RF-08 |
+| HU-02 | Como estudante/pesquisador, quero treinar uma rede neural com exemplos rotulados, para observar a reducao de erro e o ajuste dos pesos. | Alta | RF-10, RF-11 |
+| HU-03 | Como desenvolvedor JavaScript, quero executar inferencia em uma rede treinada, para obter probabilidades, valores de regressao ou predicoes. | Alta | RF-09, RF-12, RF-14 |
+| HU-04 | Como integrador, quero serializar e restaurar uma rede em JSON, para salvar e reutilizar modelos entre execucoes. | Alta | RF-13 |
+| HU-05 | Como desenvolvedor, quero converter imagens em volumes de entrada, para usar redes convolucionais em problemas visuais. | Media | RF-04, RF-14, RF-15 |
+| HU-06 | Como integrador, quero usar a biblioteca tanto no navegador quanto em Node.js, para adapta-la a diferentes ambientes JavaScript. | Alta | RF-16, RF-17, RNF-01, RNF-02 |
+| HU-07 | Como usuario de demo, quero abrir exemplos interativos no navegador, para aprender visualmente como os modelos se comportam. | Media | RF-18, RNF-05 |
+| HU-08 | Como mantenedor, quero compilar os arquivos de `src/` em uma versao distribuivel, para publicar ou testar alteracoes da biblioteca. | Media | RF-19, RNF-03, RNF-04 |
+| HU-09 | Como mantenedor, quero executar testes automatizados no Jasmine, para verificar se inicializacao, inferencia, treino e gradientes continuam funcionando. | Media | RF-20, RNF-07 |
+| HU-10 | Como estudante/pesquisador, quero experimentar o modulo de Deep Q Learning, para explorar aprendizado por reforco em JavaScript. | Baixa | RF-21 |
+| HU-11 | Como desenvolvedor, quero consultar exemplos simples no README e nas demos, para iniciar o uso da biblioteca com pouco codigo. | Media | RNF-08 |
+| HU-12 | Como usuario preocupado com privacidade, quero que as demos funcionem localmente no navegador, para evitar envio obrigatorio de dados a servidores externos. | Media | RNF-05, RNF-06, RNF-11 |
+
+## 4. Criterios de Aceitacao
+
+### HU-01 - Definir rede neural por camadas
+
+- Dado que existe uma lista de definicoes de camadas iniciada por `input`, quando o usuario chama `makeLayers`, entao a rede deve criar as camadas correspondentes.
+- Dado que uma camada `fc` ou `conv` declara ativacao, quando a rede e criada, entao a ativacao deve ser incorporada ao fluxo da rede.
+- Dado que a lista nao inicia com `input`, quando a rede e criada, entao a biblioteca deve indicar erro de configuracao.
+
+### HU-02 - Treinar rede neural
+
+- Dado que existe uma rede criada e um treinador configurado, quando o usuario chama `train` com entrada e rotulo, entao os parametros devem ser atualizados.
+- Dado um exemplo de classificacao simples, quando o treinamento ocorre com taxa adequada, entao a probabilidade da classe correta deve aumentar, conforme comportamento coberto pelos testes existentes.
+
+### HU-03 - Executar inferencia
+
+- Dado que existe uma rede criada, quando o usuario chama `forward` com um `Vol`, entao a biblioteca deve retornar um `Vol` de saida.
+- Dado que a ultima camada e `softmax`, quando o usuario chama `getPrediction`, entao a biblioteca deve retornar o indice de maior probabilidade.
+
+### HU-04 - Serializar e restaurar rede
+
+- Dado que existe uma rede criada, quando o usuario chama `toJSON`, entao a biblioteca deve retornar uma representacao JSON das camadas.
+- Dado um JSON valido de rede, quando o usuario chama `fromJSON`, entao a rede deve ser reconstruida com suas camadas e parametros.
+
+### HU-05 - Usar imagens como entrada
+
+- Dado um elemento de imagem disponivel no navegador, quando o usuario usa o utilitario de conversao, entao a imagem deve ser transformada em volume compativel com a rede.
+- Dado uma rede convolucional configurada para as dimensoes esperadas, quando o volume da imagem e processado, entao a rede deve produzir uma saida.
+
+### HU-06 - Usar no navegador e em Node.js
+
+- Dado que a biblioteca e carregada em pagina web sem CommonJS, entao ela deve ficar disponivel como `convnetjs` no escopo global.
+- Dado que a biblioteca e carregada em ambiente CommonJS, entao ela deve ser exportada por `module.exports`.
+
+### HU-07 - Abrir demos interativas
+
+- Dado que o usuario abre uma pagina em `demo/`, quando os scripts locais carregam corretamente, entao a demonstracao deve permitir interacao ou visualizacao do exemplo.
+- Dado que nao ha backend no projeto, entao a demo deve operar como pagina estatica.
+
+### HU-08 - Compilar biblioteca
+
+- Dado que o ambiente possui Apache Ant e o compressor esperado, quando o mantenedor executa o script de build, entao os arquivos em `build/` devem ser gerados conforme o processo de concatenacao e minificacao.
+
+### HU-09 - Executar testes
+
+- Dado que o usuario abre o `SpecRunner.html`, quando o Jasmine executa os testes, entao os cenarios de inicializacao, propagacao direta, treinamento e gradiente devem ser avaliados.
+
+### HU-10 - Experimentar Deep Q Learning
+
+- Dado que o usuario abre a demo de aprendizado por reforco, quando a simulacao e executada, entao o modulo experimental deve permitir observar comportamento de agente treinado por Deep Q Learning.
+
+### HU-11 - Consultar exemplos
+
+- Dado que o usuario acessa o README, quando consulta os exemplos de codigo, entao deve conseguir identificar o fluxo minimo de criacao, inferencia e treinamento de uma rede.
+
+### HU-12 - Operar localmente
+
+- Dado que as demos sao arquivos estaticos, quando executadas no navegador, entao nao devem exigir servidor ou banco de dados proprio do projeto para suas funcionalidades principais.
+
+## 5. Priorizacao
+
+| Prioridade | Criterio |
+| --- | --- |
+| Alta | Capacidade essencial para uso da biblioteca como motor de redes neurais. |
+| Media | Capacidade importante para distribuicao, aprendizado, manutencao ou ergonomia. |
+| Baixa | Capacidade experimental ou complementar ao nucleo principal. |
+
diff --git a/docs/plano-de-refatoracao.md b/docs/plano-de-refatoracao.md
new file mode 100644
index 00000000..22b7ac63
--- /dev/null
+++ b/docs/plano-de-refatoracao.md
@@ -0,0 +1,243 @@
+# Plano de Refatoracao do ConvNetJS
+
+## 1. Visao Geral
+
+Este plano define uma estrategia de refatoracao incremental para o ConvNetJS, com base nos documentos de requisitos, historias de usuario, casos de uso, README e estrutura tecnica do repositorio.
+
+O objetivo nao e reescrever a biblioteca nem alterar seu comportamento publico. A refatoracao deve preservar a API existente, os demos estaticos e a compatibilidade historica com navegador e Node.js, enquanto melhora testabilidade, manutenibilidade, organizacao interna e seguranca de evolucao.
+
+## 2. Objetivos da Refatoracao
+
+| ID | Objetivo | Relacao com requisitos |
+| --- | --- | --- |
+| OR-01 | Reduzir risco de alteracoes no motor de redes neurais por meio de testes mais amplos e repetiveis. | RF-01 a RF-14, RF-20, RNF-07 |
+| OR-02 | Preservar compatibilidade da API publica `convnetjs`, `Net`, `Vol`, `Trainer` e `SGDTrainer`. | RF-16, RF-17, HU-06 |
+| OR-03 | Melhorar validacoes e mensagens de erro sem quebrar fluxos existentes. | RF-01, RF-02, REG-01, REG-02 |
+| OR-04 | Isolar responsabilidades internas de rede, camadas, treinadores, volumes e utilitarios. | RNF-03 |
+| OR-05 | Modernizar gradualmente o processo de build e teste, mantendo os artefatos em `build/`. | RF-19, RF-20, RNF-04 |
+| OR-06 | Manter demos como exemplos estaticos funcionais e nao transforma-las em aplicacao web. | RF-18, RNF-05 |
+
+## 3. Principios e Restricoes
+
+- Preservar comportamento antes de melhorar desenho interno.
+- Refatorar em etapas pequenas, sempre acompanhadas por testes.
+- Manter os nomes publicos usados por demos e exemplos: `convnetjs.Net`, `convnetjs.Vol`, `convnetjs.Trainer`, `convnetjs.SGDTrainer`, `convnetjs.img_to_vol` e demais exports existentes.
+- Nao introduzir backend, banco de dados, autenticacao, APIs externas obrigatorias ou fluxo SaaS.
+- Nao remover `build/convnet.js` e `build/convnet-min.js` sem substituir o processo de distribuicao de forma compativel.
+- Tratar o modulo de Deep Q Learning como experimental e separado do nucleo principal.
+- Priorizar regressao funcional de `src/` antes de alterar demos ou build.
+
+## 4. Diagnostico Tecnico
+
+| Area | Situacao atual | Risco |
+| --- | --- | --- |
+| Modularizacao | Arquivos em `src/` usam IIFEs e registram simbolos em `convnetjs`. | Mudancas podem quebrar ordem de carregamento e exports globais. |
+| API publica | API historica e usada diretamente por demos e README. | Renomear ou mover simbolos quebra usuarios existentes. |
+| Build | `compile/build.xml` concatena arquivos em ordem fixa e minifica com YUI Compressor. | Processo antigo, sensivel a ordem dos arquivos e dificil de integrar a CI moderna. |
+| Testes | Jasmine 2.0 via `SpecRunner.html`, com cobertura basica de rede densa. | Refatoracoes em camadas, serializacao e otimizadores podem passar sem cobertura. |
+| Aleatoriedade | Uso amplo de `Math.random` em utilitarios, inicializacao, dropout, MagicNet e demos. | Testes podem ser instaveis e resultados dificeis de reproduzir. |
+| Validacao | Alguns erros usam `assert`, outros usam `console.log`. | Falhas podem nao interromper fluxo ou nao serem faceis de testar. |
+| Demos | Paginas HTML/JS estaticas acopladas ao bundle e scripts locais. | Alteracoes de API ou caminhos podem quebrar exemplos educacionais. |
+| Serializacao | `toJSON` e `fromJSON` existem em rede, volumes e camadas. | Mudancas internas podem quebrar modelos salvos. |
+
+## 5. Roadmap de Refatoracao
+
+### Fase 0 - Baseline e Inventario
+
+Prioridade: Alta
+
+Atividades:
+
+- Registrar a API publica atual exportada por `src/convnet_export.js` e pelo bundle `build/convnet.js`.
+- Criar uma lista de demos que devem continuar carregando: MNIST, CIFAR-10, classificacao 2D, regressao, autoencoder, trainers, image regression e RL.
+- Documentar a ordem atual de concatenacao do `compile/build.xml` como contrato temporario.
+- Confirmar quais arquivos em `build/` sao gerados e quais sao fontes mantidas manualmente.
+
+Criterios de aceite:
+
+- Existe uma lista de simbolos publicos preservados.
+- Existe uma lista de demos criticas para smoke test.
+- O time sabe quais artefatos devem ser regenerados apos mudancas em `src/`.
+
+### Fase 1 - Fortalecimento de Testes
+
+Prioridade: Alta
+
+Atividades:
+
+- Expandir `test/jasmine/spec/NeuralNetSpec.js` ou criar novos specs para cobrir:
+  - criacao de redes com `fc`, `conv`, `pool`, ativacoes, dropout e normalizacao;
+  - `forward`, `backward`, `getPrediction`, `getCostLoss`;
+  - serializacao e restauracao com `toJSON` e `fromJSON`;
+  - treinadores `sgd`, `adam`, `adagrad`, `adadelta`, `windowgrad` e `nesterov`;
+  - utilitarios de `Vol`, incluindo `clone`, `cloneAndZero`, `addFrom` e gradientes.
+- Introduzir testes deterministas para cenarios que hoje dependem de aleatoriedade.
+- Criar um smoke test documentado para abrir `SpecRunner.html` e demos principais.
+
+Criterios de aceite:
+
+- Os casos UC-01 a UC-05 possuem cobertura automatizada minima.
+- Os testes conseguem detectar quebra em criacao de rede, treino, inferencia e serializacao.
+- Testes instaveis por aleatoriedade sao reduzidos ou isolados.
+
+### Fase 2 - Validacoes e Tratamento de Erros
+
+Prioridade: Alta
+
+Atividades:
+
+- Padronizar validacoes internas para configuracoes invalidas de rede, camadas e treinadores.
+- Substituir mensagens criticas via `console.log` por erros testaveis onde isso nao quebrar compatibilidade esperada.
+- Preservar mensagens ou aliases quando forem potencialmente observados por usuarios.
+- Validar explicitamente tipos de camada desconhecidos em `Net.makeLayers`.
+- Validar formato minimo de JSON em `fromJSON` para rede e camadas.
+
+Criterios de aceite:
+
+- REG-01, REG-02 e REG-03 sao verificaveis por testes.
+- Configuracoes invalidas falham de forma previsivel.
+- Demos e exemplos existentes continuam funcionando sem alteracoes obrigatorias de uso.
+
+### Fase 3 - Separacao Interna de Responsabilidades
+
+Prioridade: Media
+
+Atividades:
+
+- Extrair a logica de "desugar" de camadas de `Net.makeLayers` para uma funcao interna testavel.
+- Centralizar o mapeamento entre `type` de camada e construtor em uma fabrica interna.
+- Reduzir duplicacao entre `makeLayers` e `fromJSON` para criacao de camadas.
+- Organizar utilitarios de erro, validacao e opcoes sem alterar o namespace publico.
+- Manter os arquivos atuais em `src/` durante esta fase para preservar o build por concatenacao.
+
+Criterios de aceite:
+
+- `Net.makeLayers` fica menor e mais legivel.
+- A criacao de camadas por definicao e por JSON usa uma fonte comum de mapeamento.
+- Nenhum nome publico e removido.
+
+### Fase 4 - Refatoracao de Treinadores e Aleatoriedade
+
+Prioridade: Media
+
+Atividades:
+
+- Separar calculo de atualizacao dos otimizadores em funcoes internas por metodo.
+- Manter `Trainer` e `SGDTrainer` como aliases publicos compativeis.
+- Introduzir um ponto interno para geracao de numeros aleatorios, com possibilidade de semente em testes.
+- Aplicar determinismo primeiro nos testes, depois avaliar exposicao opcional na API.
+- Revisar calculo de perdas de regularizacao para facilitar testes de regressao.
+
+Criterios de aceite:
+
+- Cada metodo de otimizacao pode ser testado isoladamente.
+- Os testes de treinamento deixam de depender fortemente de sorte estatistica.
+- O comportamento publico de `trainer.train(x, y)` e mantido.
+
+### Fase 5 - Build, Distribuicao e Compatibilidade
+
+Prioridade: Media
+
+Atividades:
+
+- Manter o build Ant existente inicialmente como caminho oficial.
+- Criar um script auxiliar moderno somente se ele gerar resultado funcionalmente equivalente ao bundle atual.
+- Documentar claramente como regenerar `build/convnet.js` e `build/convnet-min.js`.
+- Adicionar verificacao de que o bundle exporta `window.convnetjs` no navegador e `module.exports` no Node.js.
+- Evitar troca completa para TypeScript, ESM ou bundler moderno antes de estabilizar testes.
+
+Criterios de aceite:
+
+- RF-16, RF-17 e RF-19 continuam atendidos.
+- O bundle gerado passa nos mesmos testes do codigo fonte.
+- O README ou documento tecnico informa o processo recomendado de build.
+
+### Fase 6 - Demos e Documentacao Tecnica
+
+Prioridade: Media
+
+Atividades:
+
+- Revisar demos para remover dependencias desnecessarias de caminhos quebradicos, sem redesenhar a UI.
+- Adicionar notas curtas nas demos ou documentacao sobre seu carater estatico e educacional.
+- Garantir que exemplos do README continuem validos apos refatoracoes.
+- Documentar limitacoes conhecidas: manutencao historica limitada, ausencia de GPU, ausencia de backend e modulo RL experimental.
+
+Criterios de aceite:
+
+- UC-06 e UC-09 continuam funcionando como demos estaticas.
+- Exemplos basicos de criacao, treino e inferencia permanecem corretos.
+- A documentacao nao promete capacidades fora do escopo do projeto.
+
+## 6. Backlog Priorizado
+
+| Prioridade | Item | Resultado esperado |
+| --- | --- | --- |
+| Alta | Mapear API publica atual | Evita que refatoracao quebre usuarios existentes. |
+| Alta | Ampliar testes de `Net`, `Vol`, camadas e serializacao | Cria rede de seguranca para mudancas internas. |
+| Alta | Cobrir `Trainer` e otimizadores com testes deterministas | Reduz risco em RF-10 e RF-11. |
+| Alta | Padronizar falhas de configuracao em `makeLayers` | Melhora previsibilidade de RF-01 e RF-02. |
+| Media | Extrair fabrica de camadas | Reduz duplicacao entre criacao e restauracao. |
+| Media | Extrair `desugar` de camadas | Facilita manutencao de ativacoes, dropout e perdas. |
+| Media | Criar controle interno de aleatoriedade para testes | Reduz flakiness e facilita reproducibilidade. |
+| Media | Documentar build atual e smoke tests de demos | Protege RF-18 e RF-19. |
+| Baixa | Isolar Deep Q Learning como modulo experimental documentado | Mantem escopo claro de RF-21. |
+| Baixa | Avaliar build moderno em paralelo ao Ant | Possivel melhoria futura sem quebra imediata. |
+
+## 7. Estrategia de Testes
+
+| Tipo de teste | Escopo | Relacao |
+| --- | --- | --- |
+| Unitario | `Vol`, utilitarios, fabrica de camadas, validacoes e otimizadores. | RF-01 a RF-14 |
+| Integracao | Criar rede, treinar, inferir, serializar e restaurar. | UC-01 a UC-05 |
+| Regressao de bundle | Carregar `build/convnet.js` em browser e Node.js. | RF-16, RF-17 |
+| Smoke de demos | Abrir demos principais e verificar inicializacao sem erro. | UC-06, UC-09 |
+| Build | Executar processo de compilacao e verificar artefatos gerados. | UC-07 |
+
+## 8. Riscos e Mitigacoes
+
+| Risco | Impacto | Mitigacao |
+| --- | --- | --- |
+| Quebra da API publica historica | Alto | Mapear exports antes da refatoracao e testar aliases. |
+| Mudanca na ordem de carregamento dos arquivos | Alto | Preservar `build.xml` ate haver substituto validado. |
+| Testes instaveis por `Math.random` | Medio | Introduzir controle de aleatoriedade nos testes. |
+| Regressao em demos antigas | Medio | Criar checklist de smoke test para paginas principais. |
+| Incompatibilidade com modelos serializados | Alto | Criar testes de `toJSON`/`fromJSON` antes de alterar camadas. |
+| Refatoracao grande demais em uma etapa | Alto | Executar fases pequenas com revisao e teste a cada etapa. |
+| Modernizacao prematura de build | Medio | Tratar build moderno como opcional ate preservar saida equivalente. |
+
+## 9. Mapeamento com Casos de Uso
+
+| Caso de uso | Impacto da refatoracao | Fases relacionadas |
+| --- | --- | --- |
+| UC-01 - Definir rede neural | Melhorar validacao, fabrica de camadas e legibilidade de `makeLayers`. | Fases 1, 2, 3 |
+| UC-02 - Treinar modelo | Isolar otimizadores e testar atualizacao de parametros. | Fases 1, 4 |
+| UC-03 - Executar inferencia | Preservar `forward`, `getPrediction` e contrato de `Vol`. | Fases 1, 2 |
+| UC-04 - Usar CNN com imagem | Garantir cobertura de `conv`, `pool` e conversao de imagem. | Fases 1, 6 |
+| UC-05 - Serializar e restaurar rede | Proteger compatibilidade de JSON. | Fases 1, 2, 3 |
+| UC-06 - Executar demo no navegador | Validar demos apos mudancas em API e build. | Fases 5, 6 |
+| UC-07 - Compilar biblioteca | Documentar e estabilizar build. | Fase 5 |
+| UC-08 - Rodar testes Jasmine | Ampliar cobertura e confiabilidade. | Fase 1 |
+| UC-09 - Experimentar Deep Q Learning | Manter modulo experimental isolado. | Fase 6 |
+
+## 10. Criterios de Conclusao
+
+A refatoracao deve ser considerada concluida quando:
+
+- A API publica essencial permanece compativel com README, demos e casos de uso.
+- Os testes cobrem criacao de rede, treinamento, inferencia, serializacao, camadas principais e otimizadores.
+- O bundle distribuivel continua sendo gerado e carregado em browser e Node.js.
+- As demos principais continuam funcionando como paginas estaticas.
+- O codigo de `Net`, treinadores e criacao de camadas fica mais coeso e testavel.
+- A documentacao tecnica deixa claro como testar, compilar e validar regressao.
+
+## 11. Ordem Recomendada de Execucao
+
+1. Criar inventario da API publica e checklist de demos.
+2. Ampliar testes antes de alterar codigo produtivo.
+3. Padronizar validacoes e erros de configuracao.
+4. Refatorar criacao de camadas em `Net`.
+5. Refatorar treinadores e aleatoriedade com testes deterministas.
+6. Validar build e exports browser/Node.js.
+7. Revisar demos e documentacao apos estabilizacao.
+
diff --git a/docs/relatorio-vulnerabilidades-code-smells.md b/docs/relatorio-vulnerabilidades-code-smells.md
new file mode 100644
index 00000000..541f5695
--- /dev/null
+++ b/docs/relatorio-vulnerabilidades-code-smells.md
@@ -0,0 +1,375 @@
+# Relatorio de Vulnerabilidades e Code Smells
+
+## 1. Visao Geral
+
+Este documento apresenta uma triagem estatica local de vulnerabilidades potenciais e code smells identificados no repositorio ConvNetJS. A analise foi baseada nos documentos de requisitos, historias de usuario, casos de uso, plano de refatoracao, README, configuracoes DevSecOps e inspecao dos arquivos do projeto.
+
+Importante: este relatorio nao substitui uma execucao completa de CodeQL, SCA ou pentest. Nao ha arquivo SARIF versionado no repositorio com achados confirmados. Portanto, os itens abaixo representam riscos e smells observados por padroes de codigo, dependencias empacotadas e configuracao do projeto.
+
+## 2. Fontes Analisadas
+
+| Fonte | Finalidade |
+| --- | --- |
+| `docs/documento-de-requisitos-de-software.md` | Confirmar escopo, requisitos e restricoes do produto. |
+| `docs/historias-de-usuario.md` | Relacionar riscos aos perfis de usuario e objetivos do projeto. |
+| `docs/casos-de-uso.md` | Mapear impacto dos achados nos fluxos principais. |
+| `docs/plano-de-refatoracao.md` | Aproveitar diagnostico tecnico e prioridades de melhoria. |
+| `Readme.md` e `sobre este projeto.md` | Confirmar arquitetura, demos, build e manutencao historica. |
+| `src/` | Identificar riscos no nucleo da biblioteca. |
+| `demo/` | Identificar riscos em exemplos interativos no navegador. |
+| `test/` | Avaliar riscos e smells no ambiente de teste. |
+| `.github/` | Avaliar pipeline DevSecOps e script de relatorio SARIF. |
+| `compile/` e `build/` | Avaliar build legado e artefatos distribuidos. |
+
+## 3. Sumario Executivo
+
+| Categoria | Tipos encontrados | Ocorrencias observadas | Severidade predominante |
+| --- | ---: | ---: | --- |
+| Vulnerabilidades potenciais | 7 | 103 | Media |
+| Code smells | 7 | 2.085 | Media |
+| Total | 14 | 2.188 | Media |
+
+Principais pontos:
+
+- O maior risco pratico esta nas demos que usam `eval()` e manipulacao dinamica de HTML.
+- O projeto empacota dependencias antigas, como jQuery 1.8.3, Jasmine 2.0.0 e YUI Compressor 2.4.8.
+- Existem muitos sinais de codigo legado: `var`, comparacoes nao estritas, dependencia de namespace global e aleatoriedade sem controle.
+- A pipeline CodeQL existe, mas exclui `demo/`, `build/`, `test/` e `compile/`, justamente onde parte relevante dos riscos de demo e dependencia aparece.
+
+## 4. Vulnerabilidades Potenciais por Tipo
+
+| ID | Tipo | Quantidade | Severidade | Descricao |
+| --- | --- | ---: | --- | --- |
+| VULN-01 | Execucao dinamica de codigo com `eval()` | 12 | Alta | Demos permitem executar conteudo de textareas para recriar redes ou agentes. Isso e util para experimentacao local, mas cria risco de XSS ou execucao arbitraria caso a pagina seja publicada, receba entradas nao confiaveis ou seja usada em ambiente compartilhado. |
+| VULN-02 | Manipulacao dinamica de HTML | 32 | Media | Uso de `innerHTML` e `jQuery.html()` para renderizar strings. Em varios pontos os valores parecem internos ou gerados pela propria demo, mas o padrao aumenta risco se dados externos ou texto do usuario forem incorporados sem sanitizacao. |
+| VULN-03 | Links e recursos HTTP sem TLS | 40 | Media | README, `bower.json` e demos referenciam URLs `http://`. Isso pode permitir alteracao de conteudo em transito, downgrade de seguranca ou bloqueio por navegadores modernos quando usado em contexto HTTPS. |
+| VULN-04 | Dependencia legada jQuery 1.8.3 | 8 referencias | Alta | A biblioteca `demo/js/jquery-1.8.3.min.js` e antiga e conhecida por historico de vulnerabilidades em versoes legadas. Mesmo sendo usada nas demos, deve ser atualizada ou isolada de ambientes publicados. |
+| VULN-05 | Dependencia legada Jasmine 2.0.0 | 5 referencias | Media | O runner de testes usa Jasmine 2.0.0 empacotado localmente. O risco direto em producao e baixo, mas a dependencia antiga dificulta manutencao e pode carregar padroes inseguros em ambientes de teste publicados. |
+| VULN-06 | Ferramenta de build legada YUI Compressor 2.4.8 | 2 referencias | Media | O build depende de um `.jar` antigo em `compile/`. Alem de risco de cadeia de suprimentos e manutencao, dificulta reproducibilidade e auditoria moderna do processo de build. |
+| VULN-07 | Script de relatorio com chamada externa condicionada a chave | 4 ocorrencias | Baixa | `.github/scripts/security-review.js` pode chamar a API da OpenAI quando `OPENAI_API_KEY` esta configurada. O fluxo usa variavel de ambiente, mas envia trechos de achados SARIF para servico externo; isso deve ser documentado e tratado como decisao de privacidade/compliance. |
+
+## 5. Detalhamento das Vulnerabilidades
+
+### VULN-01 - Execucao dinamica de codigo com `eval()`
+
+Quantidade: 12 ocorrencias.
+
+Arquivos representativos:
+
+- `demo/js/classify2d.js`
+- `demo/js/regression.js`
+- `demo/js/image_regression.js`
+- `demo/js/images-demo.js`
+- `demo/js/autoencoder.js`
+- `demo/js/trainers.js`
+- `demo/js/rldemo.js`
+- `test/jasmine/lib/jasmine-2.0.0/jasmine.js`
+
+Impacto:
+
+- Permite que codigo digitado em campos da pagina seja executado no navegador.
+- Pode ser aceitavel em demos locais educacionais, mas e perigoso se hospedado publicamente sem isolamento.
+- Afeta principalmente UC-06 e UC-09, pois ambos envolvem demos no navegador.
+
+Recomendacao:
+
+- Substituir `eval()` por parser restrito de configuracao JSON sempre que possivel.
+- Quando a execucao dinamica for mantida por finalidade educacional, isolar em sandbox, documentar o risco e evitar hospedar com dados sensiveis.
+- Excluir ou proteger demos com `eval()` em publicacoes voltadas a usuarios finais.
+
+### VULN-02 - Manipulacao dinamica de HTML
+
+Quantidade: 32 ocorrencias.
+
+Arquivos representativos:
+
+- `demo/speedtest.html`
+- `demo/js/classify2d.js`
+- `demo/js/image_regression.js`
+- `demo/js/images-demo.js`
+- `demo/js/autoencoder.js`
+- `demo/js/automatic.js`
+
+Impacto:
+
+- Uso de strings HTML montadas dinamicamente amplia superficie de XSS.
+- Parte do conteudo e interno, mas o padrao e arriscado se evoluir para receber entrada de usuario, datasets externos ou parametros de URL.
+
+Recomendacao:
+
+- Preferir `textContent` para texto.
+- Criar elementos DOM de forma programatica quando houver dados variaveis.
+- Sanitizar qualquer HTML gerado a partir de entrada externa.
+
+### VULN-03 - Links e recursos HTTP sem TLS
+
+Quantidade: 40 ocorrencias.
+
+Arquivos representativos:
+
+- `Readme.md`
+- `bower.json`
+- `demo/*.html`
+- `demo/js/npgmain.js`
+- `demo/js/pica.js`
+- `test/jasmine/lib/jasmine-2.0.0/*.js`
+
+Impacto:
+
+- Recursos carregados via HTTP podem ser alterados em transito.
+- Navegadores modernos podem bloquear conteudo misto se as demos forem servidas por HTTPS.
+- Documentacao aponta usuarios para links antigos e potencialmente inseguros.
+
+Recomendacao:
+
+- Migrar links externos para `https://` quando os destinos suportarem TLS.
+- Evitar carregar fontes ou scripts remotos por HTTP.
+- Para links historicos sem HTTPS, manter como referencia textual e nao como recurso carregado automaticamente.
+
+### VULN-04 - Dependencia legada jQuery 1.8.3
+
+Quantidade: 8 referencias ao arquivo nas demos.
+
+Arquivos representativos:
+
+- `demo/js/jquery-1.8.3.min.js`
+- `demo/automatic.html`
+- `demo/autoencoder.html`
+- `demo/cifar10.html`
+- `demo/classify2d.html`
+- `demo/image_regression.html`
+- `demo/mnist.html`
+- `demo/trainers.html`
+
+Impacto:
+
+- jQuery 1.8.3 e muito antigo para padroes atuais.
+- Pode conter vulnerabilidades conhecidas e APIs inseguras, especialmente quando combinado com `.html()` e entradas dinamicas.
+
+Recomendacao:
+
+- Atualizar jQuery para versao mantida ou remover dependencia onde for simples.
+- Testar todas as demos apos atualizacao.
+- Se a atualizacao quebrar demos historicas, documentar risco e limitar uso a ambiente local.
+
+### VULN-05 - Dependencia legada Jasmine 2.0.0
+
+Quantidade: 5 referencias diretas no runner.
+
+Arquivos representativos:
+
+- `test/jasmine/SpecRunner.html`
+- `test/jasmine/lib/jasmine-2.0.0/`
+
+Impacto:
+
+- Baixo impacto em producao, pois fica em `test/`.
+- Mantem stack de testes antiga, dificultando automacao moderna e auditoria.
+
+Recomendacao:
+
+- Planejar atualizacao do runner de testes.
+- Manter compatibilidade com testes browser-only enquanto uma alternativa moderna nao for validada.
+
+### VULN-06 - YUI Compressor 2.4.8
+
+Quantidade: 2 referencias.
+
+Arquivos representativos:
+
+- `compile/yuicompressor-2.4.8.jar`
+- `compile/build.xml`
+- `Readme.md`
+
+Impacto:
+
+- Ferramenta antiga e empacotada como binario `.jar`.
+- Dificulta verificacao de procedencia e modernizacao da cadeia de build.
+
+Recomendacao:
+
+- Manter o build atual ate existir cobertura de regressao.
+- Avaliar substituto moderno de minificacao em paralelo.
+- Documentar hash, origem e uso do `.jar` enquanto ele permanecer no repositorio.
+
+### VULN-07 - Envio opcional de SARIF para servico externo
+
+Quantidade: 4 ocorrencias relacionadas.
+
+Arquivos representativos:
+
+- `.github/scripts/security-review.js`
+- `.github/workflows/devsecops-security.yml`
+
+Impacto:
+
+- Quando `OPENAI_API_KEY` esta configurada, achados SARIF sao enviados para analise externa.
+- Pode haver exposicao de nomes de arquivos, mensagens de regras e trechos de contexto.
+
+Recomendacao:
+
+- Documentar explicitamente esse comportamento no workflow.
+- Permitir desativacao por variavel de ambiente.
+- Revisar politica de dados antes de usar em repositorios privados ou sensiveis.
+
+## 6. Code Smells por Tipo
+
+| ID | Tipo | Quantidade | Severidade | Descricao |
+| --- | --- | ---: | --- | --- |
+| SMELL-01 | Uso extensivo de `var` | 1.610 | Media | Indica estilo JavaScript legado, escopo de funcao e maior risco de hoisting inesperado. |
+| SMELL-02 | Comparacoes nao estritas | 293 | Media | Uso potencial de `==` ou `!=` aumenta risco de coercao implicita e comportamento inesperado. |
+| SMELL-03 | Acoplamento ao namespace global | 110 | Media | Uso frequente de `global.*` e registro em `convnetjs` cria acoplamento por ordem de carregamento. |
+| SMELL-04 | Aleatoriedade nao controlada | 34 | Media | Uso de `Math.random` em codigo e testes torna resultados menos reproduziveis. |
+| SMELL-05 | Logs diretos no codigo | 17 | Baixa | `console.log` aparece em biblioteca, demos, testes e scripts; dificulta controle de saida e tratamento padronizado de erro. |
+| SMELL-06 | Comentarios TODO/FIXME | 14 | Baixa | Indicam dividas tecnicas conhecidas, incluindo perda e organizacao de utilitarios. |
+| SMELL-07 | Build e testes fortemente legados | 7 exports/referencias criticas | Media | Uso de IIFEs, `module.exports`, `window.convnetjs`, Ant e runner browser-only exige cuidado com ordem de arquivos e dificulta CI moderna. |
+
+## 7. Detalhamento dos Code Smells
+
+### SMELL-01 - Uso extensivo de `var`
+
+Quantidade: 1.610 ocorrencias.
+
+Impacto:
+
+- Escopo de funcao pode causar bugs sutis em loops e callbacks.
+- Dificulta aplicacao de regras modernas de lint.
+- Reflete padrao historico do projeto, mas aumenta custo de manutencao.
+
+Recomendacao:
+
+- Migrar gradualmente para `let` e `const`, com testes antes e depois.
+- Priorizar `src/` antes de `demo/` e dependencias empacotadas.
+
+### SMELL-02 - Comparacoes nao estritas
+
+Quantidade: 293 ocorrencias.
+
+Impacto:
+
+- Coercao implicita pode mascarar valores inesperados.
+- Em codigo numerico, diferencas entre string, numero e boolean podem gerar comportamentos dificeis de diagnosticar.
+
+Recomendacao:
+
+- Migrar para `===` e `!==` onde a equivalencia estrita preserve o comportamento.
+- Usar testes de regressao para evitar mudancas semanticas.
+
+### SMELL-03 - Acoplamento ao namespace global
+
+Quantidade: 110 ocorrencias de `global.*` em `src/` e `build/`.
+
+Impacto:
+
+- A ordem de concatenacao em `compile/build.xml` se torna critica.
+- Refatoracoes em arquivos isolados podem quebrar outros modulos silenciosamente.
+- Dificulta uso de ferramentas modernas de analise e bundling.
+
+Recomendacao:
+
+- Introduzir fabrica interna de camadas e mapa central de exports.
+- Preservar `window.convnetjs` e `module.exports` como API publica.
+- Refatorar internamente antes de alterar formato de modulo.
+
+### SMELL-04 - Aleatoriedade nao controlada
+
+Quantidade: 34 ocorrencias.
+
+Impacto:
+
+- Testes podem falhar ou passar dependendo da sorte.
+- Experimentos nao sao plenamente reproduziveis.
+- Afeta inicializacao de pesos, dropout, MagicNet, demos e testes.
+
+Recomendacao:
+
+- Criar gerador de numeros aleatorios injetavel ou configuravel para testes.
+- Manter `Math.random` como padrao para compatibilidade quando nenhuma semente for definida.
+
+### SMELL-05 - Logs diretos no codigo
+
+Quantidade: 17 ocorrencias.
+
+Impacto:
+
+- Alguns erros sao apenas impressos, sem interromper execucao.
+- Dificulta automacao de testes que esperam excecoes ou resultados estruturados.
+- Mistura diagnostico, aviso e erro em `console.log`.
+
+Recomendacao:
+
+- Padronizar erros e warnings.
+- Substituir logs criticos por excecoes testaveis quando isso nao quebrar demos.
+- Manter logs de demo apenas quando forem parte da visualizacao educacional.
+
+### SMELL-06 - TODO/FIXME
+
+Quantidade: 14 ocorrencias.
+
+Impacto:
+
+- Indica pontos conhecidos de divida tecnica.
+- Alguns TODOs aparecem em dependencias de teste empacotadas, mas ha tambem comentario relevante em `src/convnet_trainers.js` sobre reorganizacao de calculo de loss.
+
+Recomendacao:
+
+- Classificar TODOs entre codigo proprio e dependencias empacotadas.
+- Converter TODOs do codigo proprio em itens de backlog rastreaveis.
+
+### SMELL-07 - Build e testes legados
+
+Quantidade: 7 referencias criticas a exports browser/Node e processo antigo.
+
+Impacto:
+
+- Build por concatenacao depende de ordem fixa.
+- Testes dependem de runner HTML manual.
+- Modernizacao direta pode quebrar API publica e demos.
+
+Recomendacao:
+
+- Preservar fluxo atual ate ampliar cobertura de testes.
+- Adicionar comandos automatizaveis para smoke tests.
+- Avaliar build moderno somente em paralelo, conforme definido no plano de refatoracao.
+
+## 8. Relacao com Casos de Uso
+
+| Caso de uso | Riscos mais relevantes | Observacao |
+| --- | --- | --- |
+| UC-01 - Definir rede neural | SMELL-03, SMELL-05, SMELL-07 | Acoplamento global e validacoes por log dificultam evolucao segura de `makeLayers`. |
+| UC-02 - Treinar modelo | SMELL-04, SMELL-05 | Aleatoriedade e logs dificultam reprodutibilidade e diagnostico de treino. |
+| UC-03 - Executar inferencia | SMELL-03, SMELL-04 | API publica deve ser preservada durante qualquer modernizacao. |
+| UC-04 - Usar CNN com imagem | VULN-02, SMELL-04 | Demos de imagem manipulam DOM e dependem de dados dinamicos. |
+| UC-05 - Serializar e restaurar rede | SMELL-03, SMELL-07 | Mudancas internas podem quebrar modelos serializados se nao houver testes. |
+| UC-06 - Executar demo no navegador | VULN-01, VULN-02, VULN-03, VULN-04 | Principal concentracao de riscos de seguranca esta nas demos. |
+| UC-07 - Compilar biblioteca | VULN-06, SMELL-07 | Build legado deve ser estabilizado antes de modernizacao. |
+| UC-08 - Rodar testes Jasmine | VULN-05, SMELL-07 | Testes antigos precisam ser preservados enquanto se planeja atualizacao. |
+| UC-09 - Experimentar Deep Q Learning | VULN-01, SMELL-04 | Demo de RL usa configuracao dinamica e comportamento experimental. |
+
+## 9. Priorizacao de Correcao
+
+| Prioridade | Itens | Acao recomendada |
+| --- | --- | --- |
+| Alta | VULN-01, VULN-04 | Reduzir ou isolar `eval()` nas demos e atualizar/remover jQuery legado. |
+| Alta | SMELL-03, SMELL-07 | Mapear API publica e proteger ordem de build antes de refatorar. |
+| Media | VULN-02, VULN-03, VULN-06 | Sanitizar HTML dinamico, migrar links para HTTPS e documentar/substituir YUI Compressor. |
+| Media | SMELL-01, SMELL-02, SMELL-04 | Migrar JS legado gradualmente, usar comparacoes estritas e controlar aleatoriedade. |
+| Baixa | VULN-05, VULN-07, SMELL-05, SMELL-06 | Atualizar Jasmine, documentar envio externo SARIF, padronizar logs e converter TODOs em backlog. |
+
+## 10. Plano de Acao Resumido
+
+1. Executar CodeQL e anexar o SARIF real ao processo de revisao.
+2. Revisar demos com `eval()` e decidir entre remover, substituir por JSON ou isolar por sandbox.
+3. Atualizar jQuery ou limitar demos antigas a ambiente local documentado.
+4. Migrar links HTTP para HTTPS.
+5. Criar testes de regressao para `Net`, `Vol`, `Trainer`, serializacao e demos principais.
+6. Padronizar tratamento de erros antes de grandes refatoracoes.
+7. Modernizar build somente apos cobertura minima de regressao.
+
+## 11. Limitacoes da Analise
+
+- As quantidades foram obtidas por busca textual estatica e podem incluir ocorrencias em dependencias empacotadas.
+- Nao foi executada auditoria online de CVEs ou banco de vulnerabilidades.
+- Nao foi executado CodeQL local com resultados SARIF neste relatorio.
+- Nem toda ocorrencia representa vulnerabilidade exploravel; alguns achados sao riscos condicionais ao modo como as demos forem publicadas ou usadas.
+
diff --git a/sobre este projeto.md b/sobre este projeto.md
new file mode 100644
index 00000000..cb793d58
--- /dev/null
+++ b/sobre este projeto.md	
@@ -0,0 +1,112 @@
+# Sobre este projeto
+
+## Visão geral do repositório
+
+Esse repositório é o `convnetjs` do Andrej Karpathy. É uma biblioteca JavaScript para redes neurais e convolucionais, com foco em uso no navegador e compatibilidade com Node.js. Não é uma aplicação de servidor com banco de dados; é um motor de Deep Learning escrito em JS.
+
+## Para que serve
+
+- Implementa redes neurais em JavaScript.
+- Suporta:
+  - camadas totalmente conectadas (`fc`)
+  - camadas convolucionais
+  - pooling
+  - normalização
+  - funções de perda como `softmax`, `SVM`, `L2`
+  - otimizadores / treinadores como SGD, Adagrad, Adadelta
+  - módulo experimental de Reinforcement Learning (Deep Q Learning)
+- Inclui demos de exemplos em browser, como MNIST, CIFAR-10, regressão, autoencoder e RL.
+
+## Linguagem e execução
+
+- Linguagem: **JavaScript**
+- Execução:
+  - browser
+  - Node.js (há wrappers `module.exports` em `src/convnet_export.js` e em `build/*`)
+- Não há TypeScript.
+- Não há `package.json` neste workspace, mas há `bower.json` indicando uso como biblioteca front-end/AMD/Node.
+
+## Arquitetura do software
+
+### Camadas principais
+
+- `src/`
+  - Contém a implementação modular do motor de rede neural.
+  - Arquivos principais:
+    - `convnet_net.js` — rede neural, criação de camadas e fluxo forwards/backwards
+    - `convnet_trainers.js` — algoritmos de treinamento
+    - `convnet_vol.js` / `convnet_vol_util.js` — tensores / volumes de dados
+    - `convnet_util.js` — utilitários gerais
+    - `convnet_layers_*` — implementação de camadas e funções de ativação:
+      - `dotproducts`, `dropout`, `input`, `loss`, `nonlinearities`, `normalization`, `pool`
+    - `convnet_magicnet.js` — rede “mágica” / utilitários de alto nível
+    - `convnet_export.js` — exportação para Node.js / CommonJS
+
+### Build e distribuição
+
+- `build/`
+  - Contém versões concatenadas/minificadas geradas:
+    - `convnet.js`
+    - `convnet-min.js`
+  - Também há outros módulos compilados como `deepqlearn.js`, `util.js`, `vis.js`
+- `compile/`
+  - Contém `build.xml` para compilar o projeto com Apache Ant e `yuicompressor`.
+
+### Demos
+
+- `demo/`
+  - HTML e JS para demos interativas no browser.
+  - Usa arquivos estáticos e exemplos de treinamento/visualização.
+  - Não há backend próprio; os demos são páginas estáticas.
+
+## Organização de pastas
+
+- `src/` — código-fonte da biblioteca
+- `build/` — saída compilada / bundle JS
+- `compile/` — script de build Ant
+- `demo/` — demonstrações em HTML/JS/CSS
+- `test/` — testes Jasmine
+- `bower.json` — metadados do pacote Bower
+- `Readme.md` — documentação e exemplos
+
+## Banco de dados e APIs externas
+
+- **Não há banco de dados** neste repositório.
+- **Não há tabelas** ou modelagem de dados de banco de dados.
+- Não há evidência de integração com nenhuma API externa no código principal.
+- As demos usam apenas browser APIs e bibliotecas JS locais.
+
+## Dependências e bibliotecas usadas
+
+### Dependências internas / bundled
+
+- Biblioteca principal: `convnetjs` em `src/`
+- Demos utilizam bibliotecas front-end empacotadas localmente:
+  - `demo/js/jquery-1.8.3.min.js`
+  - `demo/js/pica.js`
+  - possivelmente outras utilidades JS para manipulação de imagem e UI
+
+### Dependências de build ou pacote
+
+- `bower.json` declara `main: build/convnet.js`, e suporte para:
+  - AMD
+  - ES6
+  - globals
+  - Node
+  - YUI
+
+## Testes
+
+- Existe um conjunto de testes em `test/jasmine/`
+- Arquivos relevantes:
+  - `test/jasmine/SpecRunner.html`
+  - `test/jasmine/spec/NeuralNetSpec.js`
+- O framework de teste usado é **Jasmine 2.0**
+- Os testes estão configurados para rodar no browser via HTML runner.
+
+## Informações relevantes adicionais
+
+- O README diz que o projeto não está mais ativamente mantido.
+- A compilação do JS é feita por concatenação dos arquivos `src/` e minificação com `yuicompressor`.
+- Há suporte histórico para uso com `npm install convnetjs`, mesmo que aqui não exista `package.json`.
+- O foco é em pesquisa/educação de redes neurais, não em aplicação web backend.
diff --git a/test/jasmine/SpecRunner.html b/test/jasmine/SpecRunner.html
index f1043253..4c55620c 100644
--- a/test/jasmine/SpecRunner.html
+++ b/test/jasmine/SpecRunner.html
@@ -12,10 +12,26 @@
   <script type="text/javascript" src="lib/jasmine-2.0.0/boot.js"></script>
 
   <!-- include source files here... -->
-  <script type="text/javascript" src="../../build/convnet.js"></script>
+  <script type="text/javascript" src="../../src/convnet_init.js"></script>
+  <script type="text/javascript" src="../../src/convnet_util.js"></script>
+  <script type="text/javascript" src="../../src/convnet_vol.js"></script>
+  <script type="text/javascript" src="../../src/convnet_vol_util.js"></script>
+  <script type="text/javascript" src="../../src/convnet_layers_dotproducts.js"></script>
+  <script type="text/javascript" src="../../src/convnet_layers_pool.js"></script>
+  <script type="text/javascript" src="../../src/convnet_layers_input.js"></script>
+  <script type="text/javascript" src="../../src/convnet_layers_loss.js"></script>
+  <script type="text/javascript" src="../../src/convnet_layers_nonlinearities.js"></script>
+  <script type="text/javascript" src="../../src/convnet_layers_dropout.js"></script>
+  <script type="text/javascript" src="../../src/convnet_layers_normalization.js"></script>
+  <script type="text/javascript" src="../../src/convnet_net.js"></script>
+  <script type="text/javascript" src="../../src/convnet_trainers.js"></script>
+  <script type="text/javascript" src="../../src/convnet_magicnet.js"></script>
+  <script type="text/javascript" src="../../src/convnet_export.js"></script>
+  <script type="text/javascript" src="../../demo/js/safe-config.js"></script>
 
   <!-- include spec files here... -->
   <script type="text/javascript" src="spec/NeuralNetSpec.js"></script>
+  <script type="text/javascript" src="spec/SafeConfigSpec.js"></script>
 
 </head>
 
diff --git a/test/jasmine/lib/jasmine-2.0.0/jasmine.js b/test/jasmine/lib/jasmine-2.0.0/jasmine.js
index 24463ecb..7fa9e597 100644
--- a/test/jasmine/lib/jasmine-2.0.0/jasmine.js
+++ b/test/jasmine/lib/jasmine-2.0.0/jasmine.js
@@ -999,9 +999,7 @@ getJasmineRequireObj().DelayedFunctionScheduler = function() {
     self.scheduleFunction = function(funcToCall, millis, params, recurring, timeoutKey, runAtMillis) {
       var f;
       if (typeof(funcToCall) === 'string') {
-        /* jshint evil: true */
-        f = function() { return eval(funcToCall); };
-        /* jshint evil: false */
+        throw new Error('String callbacks are not supported by this vendored Jasmine runner.');
       } else {
         f = funcToCall;
       }
diff --git a/test/jasmine/spec/SafeConfigSpec.js b/test/jasmine/spec/SafeConfigSpec.js
new file mode 100644
index 00000000..38fb1a97
--- /dev/null
+++ b/test/jasmine/spec/SafeConfigSpec.js
@@ -0,0 +1,66 @@
+describe("Safe demo configuration parser", function() {
+  it("should create a network and trainer from the demo configuration dialect", function() {
+    var source = "\n\
+      layer_defs = [];\n\
+      layer_defs.push({type:'input', out_sx:1, out_sy:1, out_depth:2});\n\
+      layer_defs.push({type:'fc', num_neurons:6, activation:'tanh'});\n\
+      layer_defs.push({type:'softmax', num_classes:2});\n\
+      net = new convnetjs.Net();\n\
+      net.makeLayers(layer_defs);\n\
+      trainer = new convnetjs.SGDTrainer(net, {learning_rate:0.01, momentum:0.1, batch_size:10, l2_decay:0.001});\n\
+    ";
+
+    var config = convnetjs.demoConfig.parseNetwork(source);
+
+    expect(config.layer_defs.length).toEqual(3);
+    expect(config.net.layers.length).toEqual(5);
+    expect(config.trainer.learning_rate).toEqual(0.01);
+    expect(config.trainer.batch_size).toEqual(10);
+  });
+
+  it("should resolve constants and arithmetic expressions without executing JavaScript", function() {
+    var source = "\n\
+      var depth = 2 * 3 + 1;\n\
+      layer_defs = [];\n\
+      layer_defs.push({type:'input', out_sx:1, out_sy:1, out_depth:depth});\n\
+      layer_defs.push({type:'regression', num_neurons:28*28});\n\
+      net = new convnetjs.Net();\n\
+      net.makeLayers(layer_defs);\n\
+      trainer = new convnetjs.SGDTrainer(net, {learning_rate:1, method:'adadelta', batch_size:50});\n\
+    ";
+
+    var config = convnetjs.demoConfig.parseNetwork(source);
+
+    expect(config.layer_defs[0].out_depth).toEqual(7);
+    expect(config.layer_defs[1].num_neurons).toEqual(784);
+    expect(config.trainer.method).toEqual("adadelta");
+  });
+
+  it("should parse trainer comparison configs", function() {
+    var source = "\n\
+      var layer_defs = [];\n\
+      layer_defs.push({type:'input', out_sx:24, out_sy:24, out_depth:1});\n\
+      layer_defs.push({type:'softmax', num_classes:10});\n\
+      var LR = 0.01;\n\
+      var BS = 8;\n\
+      var L2 = 0.001;\n\
+      trainer_defs = [];\n\
+      trainer_defs.push({learning_rate:LR, method:'sgd', momentum:0.0, batch_size:BS, l2_decay:L2});\n\
+      trainer_defs.push({learning_rate:LR, method:'adam', eps:1e-8, beta1:0.9, beta2:0.99, batch_size:BS, l2_decay:L2});\n\
+      legend = ['sgd', 'adam'];\n\
+    ";
+
+    var config = convnetjs.demoConfig.parseTrainerComparison(source);
+
+    expect(config.layer_defs.length).toEqual(2);
+    expect(config.trainer_defs.length).toEqual(2);
+    expect(config.trainer_defs[1].method).toEqual("adam");
+    expect(config.legend[0]).toEqual("sgd");
+  });
+
+  it("should reject unsupported executable statements", function() {
+    expect(function() {
+      convnetjs.demoConfig.parseNetwork("window.alert('xss');");
+    }).toThrow();
+  });
+});